swigger使用文档

swagger使用方法

https://blog.csdn.net/qq_18088115/article/details/103824303

1、安装

1、安装swagger-php

使用composer安装 composer require zircote/swagger-php

2、生成接口文档

1.命令行输入

php ./vendor/zircote/swagger-php/bin/swagger 需要生成接口文档的mvc目录 -o 接口文档生成位置

例子：

php ./vendor/zircote/swagger-php/bin/swagger ./application/petstore/controller -o ./public

就可以生成相关在想生成文档的注释json文件

3、展示json文件

生成文件之后，就需要展示文件，使用官方提供的swagger-ui。
下载地址：

git clone https://github.com/swagger-api/swagger-ui.git

这个需要安装在外部可以访问的地址，一般安装在public文件夹下
安装完成之后，找到

‘swagger-ui/dist/index.html’

文件，找到第43行左右

urls:[{url:“http://www.swagger.com/swagger.json”,name:“后端文档”}]

可以通过 urls:[{url:"",name:“前端”}，{url:"",name:“后端”}]来访问，定义不同json类型的文档

这个url地址为存放json文件的地址

通过域名/swagger-ui/dist就可以查看生成的json文件

4、注释的基本的语句

    /**
    * @SWG\Swagger(
    *    swagger="2.0",
    *     schemes={"https","http"},
    *     host="www.swagger.com",
    *     basePath="/",
    *     @SWG\Info(
    *         version="1.0.0",
    *         title="测试Api 文档",
    *         description="用来测试的Api文档"
    *     )
    * )
    */

• swagger:定义的是版本号
• version：API 文档版本
• title：API 文档标题
• description：API 文档描述
• schemes：协议，可以是多个
• host：主机名
• basePath：根路径

 * @SWG\Get(
 *     path="/persons",
 *     summary="获取人",
 *     description="返回包含所有人的列表。",
 *     @SWG\Response(
 *         response=200,
 *         description="一个用户列表",
 *         @SWG\Schema(
 *             type="array",
 *             @SWG\Items(
 *                  required={"username"}
 *                  @SWG\Properties()
 *             )
 *         ),
 *     ),
 * )

• Get：请求的 HTTP 方法，支持 GET/POST/PUT/DELETE 等 HTTP 标准请求方法
• path：请求的路径
• summary：接口简介
• tags：接口标签，可以是多个
• description：接口描述，支持 Markdown 语法
• operationId：操作的 ID，需要唯一

• response 定义返回的内容
• schema属性来描述清楚具体的返回内容。

  /**
 * @SWG\Schema(
 *     type="array",
 *     @SWG\Items(
 *          required={"username"},
 *          @SWG\Property(
 *              property="firstName",
 *              type="string",
 *              description="firstName"
 *          ),
 *          @SWG\Property(
 *              property="lastName",
 *              type="string",
 *              description="lastName"
 *          ),
 *          @SWG\Property(
 *              property="username",
 *              type="string",
 *              description="username"
 *          )
 *     )
 * )
 */

较为完整的例子

/**

 * @SWG\Post(
 * path="/persons",
 * summary="Creates a person",
 * description="Adds a new person to the persons list.",
 * @SWG\Parameter(
 * name="person",
 * in="body",
 * required="true"
 * description="The person to create.",
 * @SWG\Schema(
 * required={"username"},
 * @SWG\Property(
 * property="firstName",
 * type="string"
 * ),
 * @SWG\Property(
 * property="lastName",
 * type="string"
 * ),
 * @SWG\Property(
 * property="username",
 * type="string"
 * )
 * )
 * ),
 * @SWG\Response(
 * response="200",
 * description="Persons succesfully created."
 * ),
 * @SWG\Response(
 * response="400",
 * description="Persons couldn't have been created."
 * )
 * )
   */
   

post 方法添加参数，通过 in 属性显式说明参数是在 body 中的

https://learnku.com/laravel/t/7430/how-to-write-api-documents-based-on-swagger-php#747b67

这是swagger的具体的详细教程，从初步入门到深入了解，都在这篇文章里面有讲到。比较经常用到的

使用swagger-edit快速生成接口文档json与可视化界面

安装swagger-edit

• 下载并且安装node.js
• npm install -g http-server 使用npm全局安装http-server
• 下载并解压swagger-edit工具。
  +在cmd 运行http-server
• [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-g1BWmEDs-1612418032619)(C:\Users\admin\AppData\Roaming\Typora\typora-user-images\image-20200727110255403.png)]
• 输入生成的地址

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-F6vUMMeS-1612418032623)(C:\Users\admin\AppData\Roaming\Typora\typora-user-images\image-20200727110404575.png)]

就可以进行API文档的编写