Vue项目中使用Swagger生成接口文档

╰+哭是因爲堅強的太久メ 2021-09-07 20:22 1781阅读 0赞

参考“swagger配置和注释生成文档”：[https://blog.csdn.net/qq\_38734862/article/details/107715579][https_blog.csdn.net_qq_38734862_article_details_107715579]

在线：[https://editor.swagger.io/][https_editor.swagger.io]

下载：[https://github.com/swagger-api/swagger-ui][https_github.com_swagger-api_swagger-ui]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70][]

解压后，复制整个`dist`文件夹到**服务端**的public目录下，并改名为apidocs（随意）

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 1][]

在[Swagger Editor][https_editor.swagger.io]中把文档保存为YAML或者JSON，我命名为swagger.json(或者swagger.yaml)

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 2][]

然后将文档放进api-docs文件夹，打开api-docs文件夹中的index.html，找到末尾的JavaScript，将url从[http://petstore.swagger.io/v2/swagger.json][http_petstore.swagger.io_v2_swagger.json]修改为你的文档地址

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 3][]

启动你的项目，访问：[http://localhost:3000/apidocs/index.html][http_localhost_3000_apidocs_index.html]，文档就出现了！

> 注意：这个3000是服务端的端口

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 4][]

安装swagger-editor

[https://github.com/swagger-api/swagger-editor][https_github.com_swagger-api_swagger-editor]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 5][]![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 6][]

解压出来内容如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 7][]

全局安装http-server

cnpm i -g http-server

进入swagger-editor目录，执行命令：http-server，打开展示的链接

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 8][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 9][]

基础版：

swagger: '2.0'
    
    info:
      version: 1.0.0
      title: 标题
      description: 描述：这是一个接口文档
    
    paths: {}

> type类型：![20210521092513113.png][]

# post #

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 10][]![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 11][]

swagger: '2.0'
    info:
      description: 描述：这是一个接口文档
      version: 1.0.0
      title: 接口文档
    tags:
      - name: user
        description: 关于用户的操作
    paths:
      /user:
        post:
          tags:
            - user
          summary: 创建用户
          description: 用户注册、或者管理员创建用户
          parameters:
            - in: body
              name: body
              description: 创建的用户对象
              required: true
              schema:
                $ref: '#/definitions/User'
          responses:
            200:
              description: 响应成功
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  username:
                    type: string
                    description: 用户名
                  password:
                    type: string
                    description: 密码
                  userStatus:
                    type: boolean
                    default: true
                  sex:
                    type: string
                    description: 性别。枚举[man,woman]
                    enum:
                      - man
                      - woman
                  like: 
                    type: array
                    items: 
                      type: string
                  tags: 
                    type: array
                    items: 
                      type: object
                      properties:
                        id:
                          type: integer
                          format: int64
                        name:
                          type: string
            404:
              description: 创建失败 
            default:
              description: 相应成功的操作
            
      
    definitions:
      User:
        type: object
        required:
          - username
          - password
        properties:
          id:
            type: integer
            format: int64
          username:
            type: string
            description: 用户名
          password:
            type: string
          userStatus:
            type: boolean
            default: true

# get #

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 12][]

swagger: '2.0'
    info:
      description: 描述：这是一个接口文档
      version: 1.0.0
      title: 接口文档
    tags:
      - name: user
        description: 关于用户的操作
    paths:
      /user/login:
        get:
          tags:
            - user
          summary: 用户登录
          description: 用户登录的接口
          parameters:
            - in: query
              name: username
              description: 用户名
              required: true
              type: string
            - in: query
              name: password
              description: 密码
              type: string
          responses:
            200:
              description: 响应成功

# put / delete #

url含有参数的情况，如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 13][]![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 14][]

swagger: '2.0'
    info:
      description: 描述：这是一个接口文档
      version: 1.0.0
      title: 接口文档
    tags:
      - name: user
        description: 关于用户的操作
    paths:
      /user/{username}:
        put:
          tags:
            - user
          summary: 修改用户
          description: ''
          parameters:
            - in: path
              name: username
              description: '用户名'
              required: true
              type: string
            - in: body
              name: body
              description: 要编辑的果树信息
              required: true
              schema:
                type: object
                properties:
                  username:
                    type: string
                    description: 用户名
                  password:
                    type: string
                  userStatus:
                    type: integer
                    format: int32
          responses:
            200:
              description: 修改用户成功
            404:
              description: 未找到用户
        delete:
          tags:
            - user
          summary: 根据用户名删除用户
          description: 只有管理员能删除用户
          parameters:
            - in: path
              name: username
              description: 根据用户名删除用户
              required: true
              type: string
          responses:
            200:
              description: 删除用户成功
            404:
              description: 删除失败
          deprecated: true

[https_blog.csdn.net_qq_38734862_article_details_107715579]: https://blog.csdn.net/qq_38734862/article/details/107715579
[https_editor.swagger.io]: https://editor.swagger.io/
[https_github.com_swagger-api_swagger-ui]: https://github.com/swagger-api/swagger-ui
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70]: /images/20210725/5b9fa2273b5b43d5a2bee3a5988fcd5e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 1]: /images/20210725/f246035a654f467ca5a73b60faaa2d48.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 2]: /images/20210725/6c98872dcbc7408d8e318514bbef72b2.png
[http_petstore.swagger.io_v2_swagger.json]: https://link.jianshu.com/?t=http://petstore.swagger.io/v2/swagger.json
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 3]: /images/20210725/872255ed472c4e489e0908c29786f936.png
[http_localhost_3000_apidocs_index.html]: http://localhost:3000/apidocs/index.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 4]: /images/20210725/134744ed68f14d30aeb5456fba22455a.png
[https_github.com_swagger-api_swagger-editor]: https://github.com/swagger-api/swagger-editor
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20210520100620772.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 6]: /images/20210725/117e589dae134f4bac87edb273313fc3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 7]: /images/20210725/8a87cb0783f34c6d86b5cb607cc3fdae.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 8]: /images/20210725/5d0bebb01e81496e9b24e5fa7606d882.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 9]: /images/20210725/ab98f0660bbc4eb288260af2b62fc351.png
[20210521092513113.png]: /images/20210725/98511cb8574a40418dab72ac9870dc57.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 10]: https://img-blog.csdnimg.cn/20210604144748162.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 11]: /images/20210725/ed05b276acb04609967711b3470c8127.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 12]: /images/20210725/52292a3ba93244cbba21ab55611939f5.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 13]: https://img-blog.csdnimg.cn/20210604152001576.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQwMzIzMjU2_size_16_color_FFFFFF_t_70 14]: /images/20210725/80eb193e1bff4f3e9a790890a6c1fc28.png