swoft增加swagger（丝袜哥）

一、Swagger介绍和使用

1、 什么是swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。官方网站：https://swagger.io/

Swagger采用OpenAPI规范，OpenAPI规范这类API定义语言能够帮助你更简单、快速的表述API，尤其是在API的设计阶段作用特别突出。一旦编写完成，API文档可以作为：

· 需求和系统特性描述的根据

· 前后台查询、讨论、自测的基础

· 部分或者全部代码自动生成的根据

· 其他重要的作用，比如开放平台开发者的手册

二、swagger搭建过程

安装swagger扩展包
https://github.com/zircote/swagger-php.git
下载 swagger-ui前端包
composer require swagger-api/swagger-ui
打开swagger-ui包，将dist下的index.html里面的那个url替换成.yaml文件的地址（我选择public文件下）这个.yaml文件使用./openapi --format json /home/wwwroot/swoft/app/Api/V1/ -o /home/wwwroot/swoft/public/命令生成（在vender/zircote/swagger-php/bin下执行）
安装完成之后
1.在项目中找一个地方写Api接口的分组

这里面我分了四个组【‘select’,‘update’,‘insert’,‘misc’】用来区分Api类型
2.在接口中加入swagger注解

 declare(strict_types=1);
/**
 * This file is part of Swoft.
 *
 * @link     https://swoft.org
 * @document https://swoft.org/docs
 * @contact  [email protected]
 * @license  https://github.com/swoft-cloud/swoft/blob/master/LICENSE
 */

namespace App\Api\V1;

use App\Rpc\Lib\storeFormInterface;
use Swoft\Http\Message\Request;
use Swoft\Http\Message\Response;
use Swoft\Http\Server\Annotation\Mapping\Controller;
use Swoft\Http\Server\Annotation\Mapping\RequestMapping;
use Swoft\Rpc\Client\Annotation\Mapping\Reference;
use Throwable;
/**
 * Class FieldsController
 * @Controller(prefix="/api/form")
 */
class storeFormController
{
    /**
     * @Reference(pool="field.pool")
     *
     * @var storeFormInterface
     */
    private $storeFormService;
    /**
     * @OA\Post(
     *     path="/api/form/storeForm/",    请求路径
     *     summary="表单提交数据接口",       接口描述
     *     tags={"insert"},                接口类型
     *    @OA\Parameter(
     *     name="vistor_name",  		   参数名
     *     required=true, 			 	   是否必填
     *     in="query",					   请求格式
     *     description="姓名",			   参数描述
     *     @OA\Schema(				
     *          type="string", 			   参数类型
     *          default="测试",			   默认值
     *     )
     *   ),
     *    @OA\Parameter(
     *     name="code",
     *     required=true,
     *     in="query",
     *     description="表单加密信息",
     *     @OA\Schema(
     *          type="string",
     *          default="d130zDVHsmoO8niFgiEAZbe2LRnOf9HC7j3VVeOAnuCGA8RDGLdF2/LhQt2po3sum2nXq4tr3Nue+fqbO6LAJP37cCr3gLW7rjVasJMQNX8oBNJWsmp",
     *     )
     *   ),
     *    @OA\Parameter(
     *     name="form_id",
     *     required=true,
     *     in="query",
     *     description="表单ID",
     *     @OA\Schema(
     *          type="integer",
     *          default=119,
     *     )
     *   ),
     *     @OA\RequestBody(  在当前对象获取整个http请求的body里面的所有数据（当请求为post的时候使用）
     *         @OA\MediaType(
     *             mediaType="application/json",
     *             @OA\Schema(
     *                 @OA\Property(
     *                     property="vistor_name",
     *                     default="测试"
     *                 ),
     *                 @OA\Property(
     *                     property="code",
     *                     default="d130zDVHsmoO8niFgiEAZbe2LRnOf9HC7j3VVeOAnuCGAM8RDGLdF2/LhQt2po3sum2nXq4tr3Nue+fqbO6LAJP37cCr3gLW7rjVasJMQNX8oBNJWsmp"
     *                 ),
     *                 @OA\Property(
     *                     property="form_id",
     *                     default=119
     *                 ),
     *                 example={"vistor_name": "测试", "code": "d130zDVHsmoO8niFgiEAZbe2LRnOf9HC7j3VVeOAnuCGAM8RDGLdF2/LhQt2po3sum2nXq4tr3Nue+fqbO6LAJP37cCr3gLW7rjVasJMQNX8oBNJWsmp","form_id":119}
     *             )
     *         )
     *     ),
     *     @OA\Response(                响应结果
     *         response=200,
     *         description="OK"
     *     )
     * )
     *
     * @RequestMapping(route="storeForm")
     * @param Request $request
     * @return Response
     * @throws Throwable
     */
    public function storeForm(Request $request):Response
    {
        $parame=$request->get();
        $request_url=$request->getUri()->getHost().':10001'.$request->getUri()->getPath();
        $request_ip=$request->server('remote_addr');
        $result=$this->storeFormService->storeForm($parame,$request_url,$request_ip);
        $response = \context()->getResponse();
        return $response->withData($result);
    }
}

3.通过浏览器访问swagger
访问刚才dist/index.html文件的位置（可以将这个view写成一个方法，通过控制器访问）

结果就和平常看到的Api文档一样，只不过swagger的好处就是改代码即改接口文档，可以做到接口的更改和文档同时更新。

字段类型	名称	描述
swagger	string	需要。指定正在使用的Swagger规范版本。它可以被Swagger UI和其他客户端用来解释API列表。该值必须是"2.0"。
Info	信息对象	需要。提供关于API的元数据。元数据可以由客户端使用，如果需要的话。
host	string	提供API的主机（名称或IP）。这只能是主机，不包括方案和子路径。它可能包括一个端口。如果host不包括，将使用提供文档的主机（包括端口）。在host不支持路径模板。
bashpath	string	API所服务的基本路径，相对于host。如果没有包含，则直接在API下提供API host。该值必须以一个前导斜杠（/）开始。在basePath不支持路径模板。
schemes	string	API的传输协议。值必须是从列表：“http”，“https”，“ws”，“wss”。如果schemes不包含，则使用的默认方案是用于访问规范的方案。
consumes	string	API可以使用的MIME类型列表。这对所有的API都是全局的，但是可以在特定的API调用上被覆盖。值必须如MIME类型下所述。
paths	操作对象	API的可用路径和操作。
definitions	定义对象	一个对象，用于保存操作生成和使用的数据类型。
parameters	参数定义对象	保存可在各个操作中使用的参数的对象。
responses	响应定义对象	保存可用于各个操作的响应的对象。
tags	标签对象	对接口定义，所属的标签，唯一的
description	string	API的简短说明。
version	string	Api版本的说明
responses	响应定义对象	保存可用于各个操作的响应的对象。
summary	string	接口的简短摘要。为了在swagger-ui中获得最大的可读性

参数对象描述： @SWG\Parameter 描述一个单一的操作参数

字段类型	名称	描述
name	string	参数的名称。参数名称区分大小写。
in	string	参数的位置。可能的值是“query”，“header”，“path”，“formData”或“body”。
type	string	参数的类型。取值权限：“string”，“number”，“integer”，“bollean”，“array”，“file”。
required	boolean	确定此参数是否是必需的。其默认值是false。
default	任何类型	参数默认值

响应对象描述： @SWG\Response

字段类型	名称	描述
description	string	响应的简短描述
schema	模式对象	响应结构的定义。它可以是一个数组或一个对象。如果此字段不存在，则表示没有内容作为响应的一部分返回。
headers	标头对象	与响应一起发送的标题列表。
examples	示例对象	响应消息的一个例子

swagger官方文档:https://bfanger.nl/swagger-explained/