先说什么是Swagger, Swagger的使用目的是方便优美的呈现出接口API的各种定义, 生成API文档, 包括参数, 路径之类. 有时后端改了API的参数或者其他设置, 前端直接看这个Swagger UI就可以, 方便项目管理和团队协作.
官网: http://swagger.io/
参数文档: https://github.com/swagger-api/swagger-ui#parameters
这东西咋用呢? 说白了就是安装Swagger套件, 然后API代码里写注释, 用Swagger后端程序跑API来提取注释, 生成一个json文件, 再通关Swagger前端来美化,整理JSON数据.
我们的 restful api 项目采用 phalcon 框架,整体结构很简单,我们只需要用 swagger 扫描 controller 目录即可.
下简称我们的 php api 项目为 php_api_project.
服务器采用 nginx.
首先在composer.json文件里面添加：
"darkaonline/l5-swagger": "7.*",
"zircote/swagger-php": "^3.0"composer.json添加后的如下内容:
然后开始安装:
composer update 进行安装，也可以直接安装：
composer require darkaonline/l5-swagger:7.* -vvv
composer require zircote/swagger-php:^3.0 -vvv
在安装过程中可能会出现下面的错误：
Could not scan for classes inside "database/seeds" which does not appear to be a file nor a folder
这个时候执行以下民间就可以解决：
php artisan make:seeder UserTableSeeder
或者会出现如下的错误：
PHP Composer install“cannot allocate memory” error
这个时候改一下内存大小：
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
出现这个错误，需要改一下ui的js文件：
在vender/L5-Swagger/resources/views/index.blade.php目录下面找到：
改成下面的方法：
这样就成功了，不会报错了。
接着就可以安装完成了：
我们打开地址：会出现下面的配置说明：
我们建立一个BaseController里面写如下内容：
/**
* @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{}
这样就可以看到效果了。
比如我现在是一个json请求数据格式：
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, '请求成功');
}执行以下命令：
这个时候你可以下载这个json文件。
口描述 (@OA\Get, @OA\Post 等) 常用字段:
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]
参数列表
参数描述 (@SWG\Parameter) 常用字段:
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 传递时规矩挺多,我没用到.用到的同学自己看文档吧.可以通过这个：
https://github.com/zircote/swagger-php
https://swagger.io/specification/
去看里面的一些注解方法。