Swagger mit statischer Dokumentation

Question

Ich suche Swagger, um meine erholsame Schnittstelle zu dokumentieren. Das Problem ist, dass ich meine Dokumentation nicht automatisch generieren möchte, indem ich meinen Code annotiere. Grundsätzlich möchte ich mein internes Datenmodell nicht mit dem virtuellen Datenmodell koppeln, das von der Schnittstelle zur Verfügung gestellt wird. Es scheint, dass ich nur meinen Server eine Resources.json-Datei und dann eine entsprechende JSON-Datei für jeden Ressourcen-Handler bereitstellen lassen kann. Als ich dies jedoch versuchte, stieß ich auf viele kleine Fehler, während ich versuchte, die korrekte JSON-Syntax zu definieren und die richtigen HTTP-Header-Antwortfelder zur Verfügung zu stellen.

Hat jemand Swagger auf diese Weise benutzt? Jeder hat einige Unterlagen oder Beispiele? Alles, was ich finden konnte, konzentrierte sich auf die Verwendung der Client-Bibliotheken, um Dinge für Sie zu generieren.

Answer 1

Ich habe statische JSON-Dateien für Swagger zuvor erstellt. In der Dokumentation fehlt es irgendwie an der Beschreibung des jsons, der benötigt wird, um zur Arbeit zu kommen.

Wenn Sie auf ihre spec schauen und ihr Beispiel petstore.json betrachten. Sie sollten in der Lage sein, eine gute Idee zu bekommen, wie Sie Ihren JSON strukturieren können.

Oder sehen Sie sich meine Beispiele an.

Wenn Sie weitere Fragen haben, zögern Sie nicht zu fragen.

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": [ ] 
       } 
      ] 
     }, 
    ] 
} 

Answer 2

I json von PHP-Dateien mit Prahlerei PHP hier geschaffen haben, ist mein Code, wenn jemand für sucht, hoffe, es hilft

<?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"; 
} 

Modellcode:

<?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; 



} 

}

hier wir JSON-Code für Prahlerei UI:

{ 
"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" 
] 
} 

Geben Sie den json Weg in api-doc.json