Swagger con documentación estática

Question

Estoy buscando usar Swagger para documentar mi relajante interfaz. El problema es que no quiero generar automáticamente mi documentación anotando mi código. Básicamente, no quiero vincular mi modelo de datos interno con el modelo de datos virtual expuesto por la interfaz. Parece que puedo hacer que mi servidor proporcione un archivo Resources.json y luego un archivo JSON correspondiente para cada manejador de recursos. Sin embargo, cuando probé esto, me encontré con muchos pequeños problemas al intentar definir la sintaxis correcta de JSON y proporcionar los campos de respuesta de encabezado HTTP correctos.

¿Alguien ha usado Swagger de esta manera? Alguien tiene alguna documentación o ejemplos? Todo lo que pude encontrar se centró en simplemente usar las bibliotecas del cliente para generar cosas para usted.

Answer 1

He creado archivos json estáticos para swagger antes. La documentación es deficiente al describir el json requerido para que swagger funcione.

Si mira su spec y mira su ejemplo petstore.json. Deberías poder tener una idea bastante buena de cómo estructurar tu json.

O mira mis ejemplos.

Si tiene más preguntas no dude en preguntar.

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

He creado JSON de archivos PHP usando PHP arrogancia aquí es mi código si alguien está buscando, creo que sirve

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

Código de modelo:

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



} 

}

aquí nos JSON código para la interfaz de usuario arrogancia:

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

Dale la ruta de JSON en api-doc.json