运用Swagger编写API文档

梦里梦外; 2023-07-13 03:56 3阅读 0赞

### 运用Swagger编写API文档 ###

*  1 Swagger
 *   *  1.1 什么是Swagger
     *  1.2 SwaggerEditor安装与启动
     *  1.3 编写示例
     *  1.4 SwaggerUI环境搭建

# 1 Swagger #

## 1.1 什么是Swagger ##

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。  
前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要， swagger 就是一款让你更好的书写API文档的框架。

## 1.2 SwaggerEditor安装与启动 ##

1）全局安装http-server  
http-server是一个简单的零配置命令行http服务器  
npm install ‐g http‐server  
2）启动swagger-editor  
cmd进入swagger-editor所在文件夹  
http‐server swagger‐editor  
浏览器打开： http://localhost:8080  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI_size_16_color_FFFFFF_t_70]

## 1.3 编写示例 ##

swagger: "2.0"
    info:
      version: 1.0.0
      title: 物流模块 API
    host: api.logistics.chen
    basePath: /logistics
    tags:
      - name: area
        description: 地区相关接口
      - name: calculation
        description: 计算方式相关接口
      - name: channel
        description: 渠道相关接口
      - name: company
        description: 货运公司相关接口
    schemes:
      - http
    paths: 
      /area:
        post:
          tags:
          - area
          summary: 新增地区
          parameters: 
            - in: body
              name: body
              description: 地区实体类
              required: true
              schema: 
                $ref: '#/definitions/Area'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiResponse'
        get:
          tags:
          - area
          summary: 返回地区列表
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiAreaListResponse'
      /area/{areaId}:
        put: 
          tags:
            - area
          summary: 根据ID修改地区
          parameters: 
            - name: areaId
              in: path
              description: 地区ID
              required: true
              type: string
              
            - in: body
              name: body
              description: 地区实体类
              required: true
              schema: 
                $ref: '#/definitions/Area'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiResponse'
        delete:
          tags:
            - area
          summary: 根据ID删除地区
          parameters: 
            - name: areaId
              in: path
              description: 地区ID
              required: true
              type: string
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiResponse'
        get:
          tags:
            - area
          summary: 根据ID查询地区
          parameters: 
            - name: areaId
              in: path
              description: 地区ID
              required: true
              type: string
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiAreaResponse'
      /area/search:
        post:
          tags: 
            - area
          summary: 根据条件查询地区列表
          parameters: 
            - in: body
              name: body
              description: 地区实体类
              required: true
              schema: 
                $ref: '#/definitions/Area'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiAreaListResponse'
      /area/search/{page}/{size}:
        post:
          tags: 
            - area
          summary: 根据条件查询地区列表 分页
          parameters: 
            - name: page
              in: path
              description: 页码
              required: true
              type: integer
              format: int32
            - name: size
              in: path
              description: 页大小
              required: true
              type: integer
              format: int32  
            - in: body
              name: body
              description: 地区实体类
              required: true
              schema: 
                $ref: '#/definitions/Area'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiAreaPageResponse'
      
      /company:
        post:
          tags:
          - company
          summary: 新增货运公司
          parameters: 
            - in: body
              name: body
              description: 货运公司实体类
              required: true
              schema: 
                $ref: '#/definitions/Company'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiResponse'
        get:
          tags:
          - company
          summary: 返回货运公司列表
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiCompanyListResponse'
      /company/{companyId}:
        put: 
          tags:
            - company
          summary: 根据ID修改公司
          parameters: 
            - name: companyId
              in: path
              description: 公司ID
              required: true
              type: string
              
            - in: body
              name: body
              description: 公司实体类
              required: true
              schema: 
                $ref: '#/definitions/Company'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiResponse'
        delete:
          tags:
            - company
          summary: 根据ID删除公司
          parameters: 
            - name: companyId
              in: path
              description: 公司ID
              required: true
              type: string
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiResponse'
        get:
          tags:
            - company
          summary: 根据ID查询公司
          parameters: 
            - name: companyId
              in: path
              description: 公司ID
              required: true
              type: string
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiCompanyResponse'
      /company/search:
        post:
          tags: 
            - company
          summary: 根据条件查询公司列表
          parameters: 
            - in: body
              name: body
              description: 公司实体类
              required: true
              schema: 
                $ref: '#/definitions/Company'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiCompanyListResponse'
      /company/search/{page}/{size}:
        post:
          tags: 
            - company
          summary: 根据条件查询地区列表 分页
          parameters: 
            - name: page
              in: path
              description: 页码
              required: true
              type: integer
              format: int32
            - name: size
              in: path
              description: 页大小
              required: true
              type: integer
              format: int32  
            - in: body
              name: body
              description: 公司实体类
              required: true
              schema: 
                $ref: '#/definitions/Company'
          responses:
            200:
              description: 成功响应
              schema:
                $ref: '#/definitions/ApiCompanyPageResponse'
      
    definitions:
      Area:
        type: object
        properties:
          id: 
            type: string
            description: ID
          name: 
            type: string
            description: 地区名称
          code:
            type: string
            description: 地区简码
      ApiAreaResponse: 
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息
          data:
            $ref: '#/definitions/Area'
      AreaList:
        type: array
        items:
          $ref: '#/definitions/Area'
      ApiAreaListResponse: 
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息
          data:
            $ref: '#/definitions/AreaList'
      ApiAreaPageResponse:
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息
          data:
            properties:
              total:
                type: integer
                format: int32
              rows:
                $ref: '#/definitions/AreaList'
      
      Company:
        type: object
        properties:
          id: 
            type: string
            description: ID
          name: 
            type: string
            description: 公司名称
          code:
            type: string
            description: 公司简介
      ApiCompanyResponse: 
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息
          data:
            $ref: '#/definitions/Company'
      CompanyList:
        type: array
        items:
          $ref: '#/definitions/Company'
      ApiCompanyListResponse: 
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息
          data:
            $ref: '#/definitions/CompanyList'
      ApiCompanyPageResponse:
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息
          data:
            properties:
              total:
                type: integer
                format: int32
              rows:
                $ref: '#/definitions/CompanyList'
    
      ApiResponse:
        type: object
        properties:
          flag:
            type: boolean
            description: 是否成功
          code: 
            type: integer
            format: int32
            description: 返回码
          message:
            type: string
            description: 返回信息

## 1.4 SwaggerUI环境搭建 ##

1.新建works文件夹，然后进入到 works目录，执行初始化命令：npm init ，出现如下信息，填的地方可以随便写，也可以不写  
2. 解压swagger-ui-master.zip,将dist 文件夹复制到 works下  
3. 安装express cd works>npm install express  
4. 在works文件夹下创建index.js

var express = require('express');
    var app = express();
    app.use('/root', express.static('dist'));
    app.get('/', function (req, res) {
      res.send('Hello World!');
    });
    app.listen(3000, function () {
      console.log('Example app listening on port 3000!');
    });

5.然后启动，并运行查看，如上代码为3000端口，如有冲突请自行修改

cd works>node index.js // 启动命令  
Example app listening on port 3000!

浏览器输入地址：http://127.0.0.1:3000/root/index.html  
6.使用自己的api文档  
works/dist/index.html下 修改  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI_size_16_color_FFFFFF_t_70 1]![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI_size_16_color_FFFFFF_t_70 2]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200310144655755.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200310144557508.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200310144820901.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2E5NzQ5ODYwNDI=,size_16,color_FFFFFF,t_70