Let me talk about what Swagger is. The purpose of using Swagger is to conveniently and beautifully present the various definitions of the interface API, generate API documentation, including parameters, paths and the like. Sometimes the back-end changes the API parameters or other settings, and the front-end directly looks at this Swagger UI can be used to facilitate project management and team collaboration.
Official website: http://swagger.io/
Parameter documentation: https://github.com/swagger-api/swagger-ui#parameters
How does this thing work? To put it bluntly, install the Swagger suite, then write comments in the API code, use the Swagger back-end program to run the API to extract the comments, generate a json file, and then pass the Swagger front-end to beautify and organize the JSON data.
Our restful api project uses the phalcon framework, the overall structure is very simple, we only need to scan the controller directory with swagger.
Hereinafter referred to as our php api project is php_api_project. The
server uses nginx.
First add in the composer.json file:
"darkaonline/l5-swagger": "7.*",
"zircote/swagger-php": "^3.0"The following content after adding composer.json:
Then start the installation:
Composer update can be installed, or it can be installed directly:
composer require darkaonline/l5-swagger:7.* -vvv
composer require zircote/swagger-php:^3.0 -vvv
The following errors may appear during the installation process:
Could not scan for classes inside "database/seeds" which does not appear to be a file nor a folder
At this time, it can be solved by executing the following folks:
php artisan make:seeder UserTableSeeder
Or the following error will appear:
PHP Composer install“cannot allocate memory” error
Change the memory size at this time:
sudo /bin/dd if=/dev/zero of=/var/swap.1 bs=1M count=4096
sudo /sbin/mkswap /var/swap.1
sudo /sbin/swapon /var/swap.1
When this error occurs, you need to change the ui js file:
Find under the vendor / L5-Swagger/resources/views/index.blade.php directory:
Change to the following method:
This is successful and no error will be reported.
Then the installation can be completed:
We open the address: the following configuration instructions will appear:
We create a BaseController and write the following:
/**
* @OA\Info(
* version="1.0",
* title="Laravel7.8 Restful API说明文档",
* description="Laravel7.8 Restful API说明文档, 该API可供Laravel7.8以上",
* termsOfService="http://huage.com",
* @OA\Contact(
* name="Laravel7.8中文支持",
* url="http://huage.com",
* email="[email protected]"
* ),
* @OA\License(
* name="非开源项目",
* url="http://huage.com"
* ),
* )
* @OA\Server(
* url=L5_SWAGGER_CONST_HOST,
* description="Demo API Server"
* )
* @OA\Schema(
* required={"code", "message"},
* @OA\Property(
* property="code",
* type="integer",
* format="int32"
* ),
* @OA\Property(
* property="message",
* type="string"
* )
*)
* @OA\SecurityScheme(
* securityScheme="api_key",
* type="apiKey",
* in="header",
* name="api_key"
* ),
*/class BaseController extends LaravelController{}
So you can see the effect.
For example, I am now a json request data format:
class DemoController extends BaseController
{
/**
* @OA\Post(
* tags={"Demo"},
* path="/demo/jsonIndex",
* summary="json测试接口",
* @OA\RequestBody(
* required=true,
* @OA\JsonContent(
* type="object",
* required={"id", "appid"},
* @OA\Property(
* property="id",
* type="integer",
* format="int32",
* example=1,
* description="id"
* ),
* @OA\Property(
* property="appid",
* type="string",
* example="MTU5NzczNDkxMyxnaXTlj5Hlu",
* description="appid"
* )
* )
* ),
* @OA\Parameter(
* name="access-token",
* in="header",
* required=true,
* description="access-token",
* @OA\Schema(type="string")
* ),
* @OA\Response(
* response=200,
* description="OK",
* @OA\JsonContent(
* type="object",
* @OA\Property(type="object",
* property="data",
* @OA\Property(
* property="message",
* type="string",
* description="返回消息",
* @OA\Schema(type="string")
* ),
* @OA\Property(
* property="app_key",
* type="string",
* description="app_key",
* @OA\Schema(type="string")
* ),
* @OA\Property(
* property="name",
* type="string",
* description="name",
* @OA\Schema(type="string")
* )
* )
* )
* ),
* @OA\Response(
* response=401,
* description="Unauthorized"
* ),
* @OA\Response(
* response=422,
* description="Exception"
* )
* )
*/
public function jsonIndex(Request $request)
{
$data = $request->getContent();
$data = json_decode($data,true);
$id = $data['id'];
if (!intval($id)) {
throw new \Exception('非法数据');
}
$appInfo = App::Info($id);
$data['app_key'] = $appInfo->key;
$data['name'] = $appInfo->name;
return $this->response($data, '请求成功');
}Execute the following commands:
At this time you can download this json file.
Description (@OA\Get, @OA\Post, etc.) Common fields:
summary - string
接口的简要介绍,会显示在接口标头上,不能超过120个字符
description - string
接口的详细介绍
externalDocs - string
外部文档链接
operationId - string
全局唯一的接口标识
consumes - [string]
接口接收的MIME类型
produces - [string]
接口返回的MIME类型,如 application/json
schemes - [string]
接口所支持的协议,取值仅限: "http", "https", "ws", "wss"
parameters - [Parameter Object | Reference Object]
参数列表
Parameter description (@SWG\Parameter) Common fields:
name - string
参数名. 通过路径传参(in 取值 "path")时有注意事项,没用到,懒得看了...
in - string
参数从何处来. 必填. 取值仅限: "query", "header", "path", "formData", "body"
description - string
参数描述. 最好别太长
type - string
参数类型. 取值仅限: "string", "number", "integer", "boolean", "array", "file"
required - boolean
参数是否必须. 通过路径传参(in 取值 "path")时必须为 true.
default - *
默认值. 在你打算把参数通过 path 传递时规矩挺多,我没用到.用到的同学自己看文档吧.You can pass this:
https://github.com/zircote/swagger-php
https://swagger.io/specification/
Go to see some of the annotation methods inside.