利用 swagger 编辑交互式在线文档

第一步，下载swagger-ui

​ 下载后，解压找到dist目录下的index.html

 <script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region
      window.ui = ui
    }
  </script>

​ 修改url参数，可返回定义好的json或yaml文件

​ 多域名分组将url参数改为

<script>
    window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        //url: "https://petstore.swagger.io/v2/swagger.json",
        urls:[
          {name:'后台接口文档',url:"/swagger_yaml/swagger_admin.yaml"},
          {name:'前台接口文档',url:"/swagger_yaml/swagger_home.yaml"}
        ],
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
      // End Swagger UI call region

      window.ui = ui
    }
  </script>

第二步，定义接口yaml或json文件，参考文档

swagger: "2.0"                      
info:
  version: 1.0.0
  title: 前台接口文档
  description:
    前台接口文档
    <li>域名：www.laravel.com</li>
  contact:
    name: PHP开发组
schemes:
  - http
  - https
host: www.laravel.com
basePath: /
produces:
  - application/json
tags:
  - name: news
    description: 新闻
paths:
  /news/list:
    $ref: 'admin/news/paths/list.yaml'

参数说明：

swagger: swagger版本                      
info: API相关信息，也支持其他对你信息，如license,contact等
  version: 版本号，如1.0.1
  title: 文档标题
  description:文档描述
  contact: 联系信息
    name: 名称
schemes:
  - http
  - https
host: www.laravel.com
basePath: /
所有API调用的基础URL由host , schemes , basePath（根级别）组成
<scheme>://<host>/<basePath>/news/list
produces: 指定返回的内容类型
  - application/json
consumes: 指定处理请求的提交内容类型,只影响与POST，PUT和PATCH等请求主体的操作。对于像GET这样的无人机操作，它会被忽略
  - application/json
tags: 打标分组，与paths路径中的tags匹配
  - name: 组名
    description: 组描述
paths: api路径
  /news/list: 请求地址，路由参数可用{}定义，如/news/{id}
    $ref: 'admin/news/paths/list.yaml'

接口详细信息：

post: api请求方式
      tags: 标签
        - news
      summary: 描述
      description: 描述
      parameters: 请求参数
      - name: 参数名称
        type: 类型
        in: 参数位置，可使用的值 "query", "header", "path" or "cookie".
        required: 是否必须
        description: 描述
      responses: 响应
        200:
          schema:
            properties:
              status:
                type: string
                example:
                  success
                description: 状态
              code:
                type: integer
                example:
                  200
                description: 状态码
              message:
                type: string
                example:
                  '成功'
              data:
                type: object
                description: 返回值
                properties:
                  title:
                    type: string
                    description: 标题
                    example:
                      庆余年各大人物结局#新闻标题
                  content:
                    type: string
                    description: 内容
                    example:
                      庆帝死于五竹镭射眼#新闻内容
        default:
          $ref: '../../../errorResponse.yaml'

本作品采用《CC 协议》，转载必须注明作者和本文链接