我希望使用 Swagger 来记录我的宁静界面。问题是我不想通过注释我的代码来自动生成我的文档。基本上我不想将我的内部数据模型耦合到接口公开的虚拟数据模型。看来我可以让我的服务器提供一个 Resources.json 文件，然后为每个资源处理程序提供一个相应的 JSON 文件。然而，当我尝试这个时，我在尝试定义 JSON 正确语法并提供正确的 HTTP 标头响应字段时遇到了很多小问题。
有人以这种方式使用过 Swagger 吗？有人有一些文档或示例吗？我能找到的一切都围绕着简单地使用客户端库为您生成东西。
【问题讨论】：
标签： rest documentation-generation swagger
我之前为 swagger 创建了静态 json 文件。该文档有点缺乏描述使招摇工作所需的json。
如果您查看他们的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"
}
]
}
甜甜圈.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": [ ]
}
]
},
]
}
【讨论】：
我已经使用 swagger PHP 从 PHP 文件创建了 json，如果有人正在寻找，这是我的代码，希望对您有所帮助
<?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;
}
}
这里是 Swagger UI 的 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"
]
}
在api-doc.json中给出json路径
【讨论】：