2012-05-12 10 views
26

Sto cercando di usare Swagger per documentare la mia interfaccia riposante. Il problema è che non voglio generare automaticamente la mia documentazione annotando il mio codice. Fondamentalmente non voglio accoppiare il mio modello di dati interno al modello di dati virtuale esposto dall'interfaccia. Sembra che posso solo avere il mio server fornire un file Resources.json e quindi un file JSON corrispondente per ogni gestore di risorse. Tuttavia, quando ho provato questo ho incontrato un sacco di piccoli trucchi mentre tentavo di definire la sintassi corretta JSON e fornire i campi di risposta dell'intestazione HTTP corretti.Swagger With Static Documentazione

Qualcuno ha usato Swagger in questo modo? Qualcuno ha qualche documentazione o esempi? Tutto ciò che riuscivo a trovare era centrato semplicemente usando le librerie client per generare cose per te.

risposta

16

Ho creato file json statici per swagger in precedenza. La documentazione è piuttosto carente nel descrivere l'inganno necessario per far funzionare la spavalderia.

Se si guarda il loro spec e si guarda al loro esempio petstore.json. Dovresti essere in grado di avere una buona idea di come strutturare il tuo json.

Oppure guarda i miei esempi.

Se avete altre domande non esitate a chiedere.

main.json

{ 
    "apiVersion": "0.0.4542.22887", 
    "swaggerVersion": "1.0", 
    "basePath": "http://local.api.com/api/doc", 
    "apis": [ 
     { 
      "path": "/donuts", 
      "description": "Operations about donuts" 
     }, 
     { 
      "path": "/cakes", 
      "description": "Operations about cakes" 
     }, 
     { 
      "path": "/bagels", 
      "description": "Operations about bagels" 
     } 
    ] 

} 

donuts.json

{ 
    "apiVersion": "0.0.4542.22887", 
    "swaggerVersion": "1.0", 
    "basePath": "http://local.api.com/api", 
    "resourcePath": "/donuts", 
    "apis": [ 
     { 
      "path": "/donuts/{page}/{pagesize}", 
      "description": "Get donuts by page", 
      "operations": [ 
       { 
        "httpMethod": "GET", 
        "notes": "Get a donut with page and size", 
        "nickname": "getDonutsByPageAndSize", 
        "summary": "Get a collection of donuts by page and pagesize.", 
        "parameters": [ 
         { 
          "name": "page", 
          "description": "the page of the collection", 
          "dataType": "int", 
          "required": true, 
          "allowMultiple": false, 
          "paramType": "path" 
         }, 
         { 
          "name": "pagesize", 
          "description": "the size of the collection", 
          "dataType": "int", 
          "required": true, 
          "allowMultiple": false, 
          "paramType": "path" 
         } 
        ], 
        "errorResponses": [ ] 
       } 
      ] 
     }, 
    ] 
} 
+0

Grazie per i semplici esempi. Questo è veramente d'aiuto. Potresti anche fornire le richieste HTTP a cui il mio server deve rispondere per supportare adeguatamente il client JavaScript sandbox? –

+0

http://local.api.com/api/doc risponderà con main.json http://local.api.com/api/doc/donuts risponderà con donuts.json Tieni presente che main. json punta al percorso "/ ciambelle". Swagger prenderà il percorso di base da main.json (http: .../api/doc) e aggiungerà l'endpoint specifico api per la ciambella (/ ciambelle) – adamclerk

+1

Collegamenti interrotti. Inoltre, hai qualche esempio di includere l'autenticazione nelle specifiche? –

1

ho creato JSON dal file PHP utilizzando PHP spavalderia Ecco il mio codice, se qualcuno è alla ricerca di, speriamo vi sia utile

<?php 
namespace carParking\Resources; 

use Swagger\Annotations as SWG; 

/** 
* @package 
* @category 
* @subpackage 
* 
* @SWG\Resource(
* apiVersion="1.0.0", 
* swaggerVersion="1.2", 
* basePath="http://192.168.3.42/swagger/api", 
* resourcePath="/car", 
* description="Car Parking System", 
* produces="['application/json','application/xml','text/plain','text/html']" 
*) 
*/ 
class Car 
{ 
/** 
* @SWG\Api(
* path="/car/car.php?carId={carId}", 
* @SWG\Operation(
*  method="GET", 
*  summary="Find car by ID", 
*  notes="Returns a car based on ID", 
*  type="Car", 
*  nickname= "getCarById", 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="carId", 
*  description="ID of car that needs to be fetched", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="path", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=400, message="Invalid ID supplied"), 
*  @SWG\ResponseMessage(code=404, message="car not found") 
* ) 
*) 
*/ 
public function getCarById() { 
    echo "getCarById"; 
} 

/** 
* @SWG\Api(
* path="/car/fetchAll.php", 
* @SWG\Operation(
*  method="GET", 
*  summary="Fetch all parked cars", 
*  notes="Returns all cars parked", 
*  type="Car", 
*  nickname= "getAllParkedCars", 
*  authorizations={}, 
*  @SWG\ResponseMessage(code=404, message="car not found") 
* ) 
*) 
*/ 
public function getAllParkedCars() { 
    echo "getAllParkedCars"; 
} 

/** 
* @SWG\Api(
* path="/car/delete.php", 
* @SWG\Operation(
*  method="DELETE", 
*  summary="Deletes a Car", 
*  notes="Delete a parked car", 
*  type="void", 
*  nickname= "deleteCar", 
*  @SWG\Consumes("application/x-www-form-urlencoded"), 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="carId", 
*  description="ID of car that needs to be deleted", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=400, message="Invalid ID supplied"), 
*  @SWG\ResponseMessage(code=404, message="car not found") 
* ) 
*) 
*/ 
public function deleteCar() { 
    echo "deleteCar"; 
} 

/** 
* @SWG\Api(
* path="/car/add.php", 
* @SWG\Operation(
*  method="POST", 
*  summary="Add Car", 
*  notes="Add car to parking", 
*  type="array", 
*  @SWG\Items("car"), 
*  nickname= "addCar", 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="parking_section_id", 
*  description="Parking Area ID", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\Parameter(
*  name="car_number", 
*  description="Car Number", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\Parameter(
*  name="cost", 
*  description="Cost of Parking", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=400, message="Invalid ID supplied"), 
*  @SWG\ResponseMessage(code=404, message="car not found") 
* ) 
*) 
*/ 
public function addCar() { 
    echo "addCar"; 
} 

/** 
* @SWG\Api(
* path="/car/getCost.php", 
* @SWG\Operation(
*  method="POST", 
*  summary="Parking Cost of the Car Parked", 
*  notes="Parking Cost of the Car Parked", 
*  type="void", 
*  nickname= "getCost", 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="carId", 
*  description="Parking Area ID", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=405, message="Invalid input") 
* ) 
*) 
*/ 
public function getCost() { 
    echo "getCost"; 
} 

/** 
* @SWG\Api(
* path="/car/deleteAll.php", 
* @SWG\Operation(
*  method="DELETE", 
*  summary="Delete all car parking", 
*  notes="Delete all car parking", 
*  type="void", 
*  nickname= "deleteAll", 
*  @SWG\Consumes("application/x-www-form-urlencoded"), 
*  authorizations={} 
* ) 
*) 
*/ 
public function deleteAll() { 
    echo "deleteAll"; 
} 

/** 
* @SWG\Api(
* path="/car/testPut.php", 
* @SWG\Operation(
*  method="PUT", 
*  summary="Testing Put", 
*  notes="Testing Put", 
*  type="void", 
*  nickname= "testWithFormPut", 
*  @SWG\Consumes("application/x-www-form-urlencoded"), 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="firstPara", 
*  description="First Parameter", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
    *  @SWG\Parameter(
*  name="secondPara", 
*  description="Second Parameter", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=405, message="Invalid input") 
* ) 
*) 
*/ 
public function testWithFormPut() { 
    echo "testWithFormPut"; 
} 

/** 
* @SWG\Api(
* path="/car/testPatch.php", 
* @SWG\Operation(
*  method="PATCH", 
*  summary="Testing Patch", 
*  notes="Testing Patch", 
*  type="void", 
*  nickname= "testWithFormPatch", 
*  @SWG\Consumes("application/x-www-form-urlencoded"), 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="firstPara", 
*  description="First Parameter", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
    *  @SWG\Parameter(
*  name="secondPara", 
*  description="Second Parameter", 
*  required=true, 
*  type="integer", 
*  format="int64", 
*  paramType="form", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=405, message="Invalid input") 
* ) 
*) 
*/ 
public function testWithFormPatch() { 
    echo "testWithFormPatch"; 
} 

/** 
* @SWG\Api(
* path="/car/carJsonTest.php", 
* @SWG\Operation(
*  method="POST", 
*  summary="Send and parse JSON", 
*  notes="Send and parse JSON", 
*  type="void", 
*  authorizations={}, 
*  @SWG\Parameter(
*  name="body", 
*  description="Sample JSON need to be passed", 
*  required=true, 
*  type="Car", 
*  paramType="body", 
*  allowMultiple=false 
* ), 
*  @SWG\ResponseMessage(code=405, message="Invalid input") 
* ) 
*) 
*/ 
public function carJsonTest() { 
    echo "carJsonTest"; 
} 

Codice modello:

<?php 
namespace carStore\Models; 

use Swagger\Annotations as SWG; 

/** 
* @package 
* @category 
* @subpackage 
* 
* @SWG\Model(id="Car",required="parking_section_id, car_number, cost") 
*/ 
class Car 
{ 
/** 
*   @SWG\Property(name="parking_section_id",type="integer",format="int64",minimum="0.0",maximum="100.0",description="unique identifier for the parking") 
*/ 
public $parking_section_id; 

/** 
* @SWG\Property(name="car_number",type="integer",format="int64",description="unique identifier for the car") 
*/ 
public $car_number; 


/** 
* @SWG\Property(name="cost",type="integer",format="int64",description="cost for the parking") 
*/ 
public $cost; 



} 

}

codice per spavalderia UI qui ci JSON:

{ 
"basePath": "http://192.168.3.42/swagger/api", 
"swaggerVersion": "1.2", 
"apiVersion": "1.0.0", 
"resourcePath": "/car", 
"apis": [ 
    { 
     "path": "/car/add.php", 
     "operations": [ 
      { 
       "method": "POST", 
       "summary": "Add Car", 
       "nickname": "addCar", 
       "type": "array", 
       "items": { 
        "$ref": "car" 
       }, 
       "parameters": [ 
        { 
         "paramType": "form", 
         "name": "parking_section_id", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Parking Area ID", 
         "format": "int64" 
        }, 
        { 
         "paramType": "form", 
         "name": "car_number", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Car Number", 
         "format": "int64" 
        }, 
        { 
         "paramType": "form", 
         "name": "cost", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Cost of Parking", 
         "format": "int64" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 400, 
         "message": "Invalid ID supplied" 
        }, 
        { 
         "code": 404, 
         "message": "car not found" 
        } 
       ], 
       "notes": "Add car to parking", 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/car.php?carId={carId}", 
     "operations": [ 
      { 
       "method": "GET", 
       "summary": "Find car by ID", 
       "nickname": "getCarById", 
       "type": "Car", 
       "parameters": [ 
        { 
         "paramType": "path", 
         "name": "carId", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "ID of car that needs to be fetched", 
         "format": "int64" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 400, 
         "message": "Invalid ID supplied" 
        }, 
        { 
         "code": 404, 
         "message": "car not found" 
        } 
       ], 
       "notes": "Returns a car based on ID", 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/carJsonTest.php", 
     "operations": [ 
      { 
       "method": "POST", 
       "summary": "Send and parse JSON", 
       "nickname": "carJsonTest", 
       "type": "void", 
       "parameters": [ 
        { 
         "paramType": "body", 
         "name": "body", 
         "type": "Car", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Sample JSON need to be passed" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 405, 
         "message": "Invalid input" 
        } 
       ], 
       "notes": "Send and parse JSON", 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/delete.php", 
     "operations": [ 
      { 
       "method": "DELETE", 
       "summary": "Deletes a Car", 
       "nickname": "deleteCar", 
       "type": "void", 
       "parameters": [ 
        { 
         "paramType": "form", 
         "name": "carId", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "ID of car that needs to be deleted", 
         "format": "int64" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 400, 
         "message": "Invalid ID supplied" 
        }, 
        { 
         "code": 404, 
         "message": "car not found" 
        } 
       ], 
       "notes": "Delete a parked car", 
       "consumes": [ 
        "application/x-www-form-urlencoded" 
       ], 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/deleteAll.php", 
     "operations": [ 
      { 
       "method": "DELETE", 
       "summary": "Delete all car parking", 
       "nickname": "deleteAll", 
       "type": "void", 
       "notes": "Delete all car parking", 
       "consumes": [ 
        "application/x-www-form-urlencoded" 
       ], 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/fetchAll.php", 
     "operations": [ 
      { 
       "method": "GET", 
       "summary": "Fetch all parked cars", 
       "nickname": "getAllParkedCars", 
       "type": "Car", 
       "responseMessages": [ 
        { 
         "code": 404, 
         "message": "car not found" 
        } 
       ], 
       "notes": "Returns all cars parked", 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/getCost.php", 
     "operations": [ 
      { 
       "method": "POST", 
       "summary": "Parking Cost of the Car Parked", 
       "nickname": "getCost", 
       "type": "void", 
       "parameters": [ 
        { 
         "paramType": "form", 
         "name": "carId", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Parking Area ID", 
         "format": "int64" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 405, 
         "message": "Invalid input" 
        } 
       ], 
       "notes": "Parking Cost of the Car Parked", 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/testPatch.php", 
     "operations": [ 
      { 
       "method": "PATCH", 
       "summary": "Testing Patch", 
       "nickname": "testWithFormPatch", 
       "type": "void", 
       "parameters": [ 
        { 
         "paramType": "form", 
         "name": "firstPara", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "First Parameter", 
         "format": "int64" 
        }, 
        { 
         "paramType": "form", 
         "name": "secondPara", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Second Parameter", 
         "format": "int64" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 405, 
         "message": "Invalid input" 
        } 
       ], 
       "notes": "Testing Patch", 
       "consumes": [ 
        "application/x-www-form-urlencoded" 
       ], 
       "authorizations": { 

       } 
      } 
     ] 
    }, 
    { 
     "path": "/car/testPut.php", 
     "operations": [ 
      { 
       "method": "PUT", 
       "summary": "Testing Put", 
       "nickname": "testWithFormPut", 
       "type": "void", 
       "parameters": [ 
        { 
         "paramType": "form", 
         "name": "firstPara", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "First Parameter", 
         "format": "int64" 
        }, 
        { 
         "paramType": "form", 
         "name": "secondPara", 
         "type": "integer", 
         "required": true, 
         "allowMultiple": false, 
         "description": "Second Parameter", 
         "format": "int64" 
        } 
       ], 
       "responseMessages": [ 
        { 
         "code": 405, 
         "message": "Invalid input" 
        } 
       ], 
       "notes": "Testing Put", 
       "consumes": [ 
        "application/x-www-form-urlencoded" 
       ], 
       "authorizations": { 

       } 
      } 
     ] 
    } 
], 
"models": { 
    "Car": { 
     "id": "Car", 
     "required": [ 
      "car_number", 
      "cost", 
      "parking_section_id" 
     ], 
     "properties": { 
      "parking_section_id": { 
       "description": "unique identifier for the parking", 
       "type": "integer", 
       "format": "int64", 
       "minimum": "0.0", 
       "maximum": "100.0" 
      }, 
      "car_number": { 
       "description": "unique identifier for the car", 
       "type": "integer", 
       "format": "int64" 
      }, 
      "cost": { 
       "description": "cost for the parking", 
       "type": "integer", 
       "format": "int64" 
      } 
     } 
    } 
}, 
"produces": [ 
    "application/json", 
    "application/xml", 
    "text/plain", 
    "text/html" 
] 
} 

dare il percorso JSON in api-doc.json

+0

se qualcuno ha bisogno di ulteriore aiuto non esitare a chiedere :) –

+0

Ciao Syed, per favore fammi sapere, se puoi aiutarmi con questo. http://stackoverflow.com/questions/32252510/web-api-documentation-using-swagger – Raghurocks