Vênh vang với tài liệu tĩnh

Question

Tôi đang tìm cách sử dụng Swagger để ghi lại giao diện yên tĩnh của mình. Vấn đề là tôi không muốn tự động tạo tài liệu của mình bằng cách chú thích mã của tôi. Về cơ bản tôi không muốn ghép nối mô hình dữ liệu nội bộ của mình với mô hình dữ liệu ảo mà giao diện tiếp xúc. Có vẻ như tôi chỉ có máy chủ của tôi cung cấp tệp Resources.json và sau đó là tệp JSON tương ứng cho mỗi trình xử lý tài nguyên. Tuy nhiên, khi tôi thử điều này, tôi đã chạy vào rất nhiều gotchas nhỏ trong khi cố định nghĩa cú pháp đúng của JSON và cung cấp các trường phản hồi tiêu đề HTTP chính xác.

Có ai đã sử dụng Swagger theo cách này không? Bất cứ ai có một số tài liệu hoặc ví dụ? Tất cả mọi thứ mà tôi có thể tìm thấy tập trung xung quanh chỉ đơn giản bằng cách sử dụng các thư viện khách hàng để tạo ra những thứ cho bạn.

Answer 1

Tôi đã tạo các tệp json tĩnh để vênh vang trước đó. Các tài liệu là kinda thiếu trong mô tả các json cần thiết để có được swagger để làm việc.

Nếu bạn nhìn vào số spec và xem ví dụ của chúng petstore.json. Bạn sẽ có thể có được một ý tưởng khá tốt về cách cấu trúc json của bạn.

Hoặc xem ví dụ của tôi.

Nếu bạn có thêm bất kỳ câu hỏi nào, hãy hỏi.

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

Tôi đã tạo ra json từ các tập tin PHP sử dụng vênh vang PHP ở đây là mã của tôi nếu có ai đang tìm kiếm, hy vọng nó sẽ giúp

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

Mã mẫu:

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



} 

}

đây chúng tôi JSON mã cho vênh vang 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" 
] 
} 

Đưa con đường json trong api-doc.json