Swagger With Static Documentation

Question

Я ищу, чтобы использовать Swagger для документирования моего спокойного интерфейса. Проблема в том, что я не хочу автоматически генерировать мою документацию, аннотируя мой код. В принципе, я не хочу связывать свою внутреннюю модель данных с виртуальной моделью данных, открытой интерфейсом. Похоже, что я могу просто предоставить серверу файл Resource.json, а затем соответствующий JSON-файл для каждого обработчика ресурсов. Однако, когда я это пробовал, я столкнулся с множеством мелких ошибок при попытке определить правильный синтаксис JSON и предоставить правильные поля ответа HTTP-заголовка.

Кто-нибудь использовал Swagger таким образом? У кого-нибудь есть документация или примеры? Все, что я мог найти, сосредоточилось на простое использование клиентских библиотек для создания вещей для вас.

Answer 1

Я создал статические файлы json для swagger. Документация не нуждается в описании json, требуемой для того, чтобы заставить swagger работать.

Если вы посмотрите на их spec и посмотрите на их пример petstore.json. Вы должны быть в состоянии получить довольно хорошее представление о том, как структурировать ваш json.

Или посмотрите на мои примеры.

Если у вас есть еще вопросы, задайте вопросы.

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

Я создал JSON из PHP файлов с помощью PHP чванство здесь мой код, если кто-то ищет, надеюсь, что это помогает

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

Код модели:

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



} 

}

здесь нам JSON код развязность 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" 
] 
} 

Дайте путь JSon в апи-doc.json