运用Swagger编写API文档

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

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: