swagger：安装、文档编写、swaggerUI

概述

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

安装

一、解压swagger-editor

发现是一个前端工程

二、全局安装http-server(http-server是一个简单的零配置命令行http服务器)

cnpm install ‐g http‐server

三、启动：注意启动的是整个swagger‐editor

http-server swagger‐editor

四、浏览器打开：

http://localhost:8080

如果遇到跨域问题，可以按f12找到控制台发生跨域问题的地址，然后点击手动发送一次请求，就可以了。

编写城市api文档

# Example YAML to get you started quickly.
# Be aware that YAML has indentation based scoping.
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  version: "1.0.0"
  title: 城市API

# Describe your paths here
paths:
  # This is a path endpoint. Change it.
  /city:
    # This is a HTTP operation
    post:
      # Describe this verb here. Note: you can use markdown
      description: 新增城市
      # This is array of GET operation parameters:
      parameters: 
        # An example parameter that is in query and is required
        -
          name: body
          in: body
          description: 城市实体类
          schema:
            $ref: '#/definitions/City'
          
      # Expected responses for this operation:
      responses:
        # Response code
        200:
          description: ok
          # A schema describing your response object.
          # Use JSON Schema format
          schema:
            $ref: '#/definitions/ApiResponse'
    get:
      description: 获取城市列表
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ApiCityListResponse'
            
  /city/{id}:
    put:
      description: 修改城市
      parameters:
        -
          name: id
          in: path
          description: 城市id
          required: true
          type: string
        -
          name: body
          in: body
          description: 城市实体类
          schema:
            $ref: '#/definitions/City'
      responses: 
        200:
          description: OK
          schema:
            $ref: '#/definitions/ApiResponse'
    delete:
      description: 删除城市
      parameters:
        -
            name: id
            in: path
            description: 城市id
            required: true
            type: string
      responses: 
        200:
          description: OK
          schema:
            $ref: '#/definitions/ApiResponse'
    get:
      description: 根据id查询城市
      parameters:
        -
            name: id
            in: path
            description: 城市id
            required: true
            type: string
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ApiCityResponse'
    
  /city/search:
    post:
      description: 根据条件查询城市列表
      parameters: 
         -
        
          name: body
          in: body
          description: 城市实体类
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ApiCityResponse'
            
  /city/search/{page}/{size}:
    post:
      description: 城市分页列表
      parameters:
        -
          name: page
          in: path
          type: integer
          format: int32
          required: true
        -  
          name: size
          in: path
          type: integer
          format: int32
          required: true
        -
          name: body
          in: body
          description: 城市实体类
          schema:
            $ref: '#/definitions/City'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/ApiCityPageResponse'
    
            
definitions:
  City:
    type: object
    properties:
      id:
        type: string
        description: 城市ID
      name:
        type: string
        description: 城市名称
      ishot:
        type: string
        description: 是否热门
  ApiResponse:
    type: object
    properties:
      code:
        type: integer
        format: int32
      flag:
        type: boolean
      message:
        type: string
  ApiCityResponse:
    type: object
    properties:
      code:
        type: integer
        format: int32
      flag:
        type: boolean
      message:
        type: string
      data:
        $ref: '#/definitions/City'
  ApiCityListResponse:
    type: object
    properties:
      code:
        type: integer
        format: int32
      flag:
        type: boolean
      message:
        type: string
      data:
        type: array
        items:
          $ref: '#/definitions/City'
  ApiCityPageResponse:
    type: object
    properties:
      code:
        type: integer
        format: int32
      flag:
        type: boolean
      message:
        type: string
      data:
        type: object
        properties:
          total:
            type: integer
            format: int32
          rows:
            type: array
            items:
              $ref: '#/definitions/City'

swaggerUI

一、下载nginx和swaggerUI，压缩

二、找到swaggerUI的dist目录
复制dist目录下文件

三、复制到nginx的html目录下

四、启动nginx，将yml文件复制到html目录下即可。

略