Swagger avec documentation statique
Je cherche à utiliser Swagger pour documenter mon interface reposante. Le problème est que je ne souhaite pas générer automatiquement ma documentation en annotant mon code. Fondamentalement, je ne veux pas coupler mon modèle de données interne au modèle de données virtuel exposé par l'interface. Il semble que je puisse simplement demander à mon serveur de fournir un fichier Resources.json, puis un fichier JSON correspondant pour chaque gestionnaire de ressources. Cependant, lorsque j'ai essayé cela, j'ai rencontré de nombreux petits accrochages tout en essayant de définir la syntaxe correcte JSON et de fournir les champs de réponse d'en-tête HTTP corrects.
Quelqu'un a-t-il utilisé Swagger de cette manière? Quelqu'un a-t-il de la documentation ou des exemples? Tout ce que j'ai pu trouver était centré sur l'utilisation des bibliothèques clientes pour générer des choses pour vous.
J'ai déjà créé des fichiers statiques json pour swagger. La documentation manque un peu pour décrire le json requis pour que swagger fonctionne.
Si vous regardez leur spec et regardez leur exemple petstore.json . Vous devriez pouvoir avoir une assez bonne idée de la façon de structurer votre json.
Ou regardez mes exemples.
Si vous avez d'autres questions, n'hésitez pas à les poser.
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": [ ]
}
]
},
]
}
J'ai créé json à partir de fichiers PHP à l'aide de swagger PHP voici mon code si quelqu'un le recherche, j'espère que cela aide
<?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";
}
Code modèle:
<?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;
}
}
ici nous code JSON pour l'interface utilisateur swagger:
{
"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"
]
}
Donnez le chemin json dans api-doc.json