Swagger Codegen生成接口

前言：好久没写博客了，年底到前段日子很忙，加班比较多，加上本人不喜欢CV大法，这段时间一直没写博客，正好最近基于公司新项目学习swagger，故写下这篇文章供自己总结复习，供新人参考^_^。

swagger的作用

swagger是一个用于后台接口生成描述文档或者根据yaml文件生成后台接口的工具集，包括swagger UI进行功能测试、swagger Codegen进行代码生成等组件，这里介绍一下公司最近用到的使用swagger Codegen根据自定义的yaml文件生成对应的后台接口代码。

Swagger包含的工具集：

• Swagger编辑器： Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。
• Swagger UI： Swagger UI是HTML，Javascript和CSS资产的集合，可以从符合OAS标准的API动态生成漂亮的文档。
• Swagger Codegen：允许根据OpenAPI规范自动生成API客户端库（SDK生成），服务器存根和文档。
• Swagger Parser：用于解析来自Java的OpenAPI定义的独立库
• Swagger Core：与Java相关的库，用于创建，使用和使用OpenAPI定义
• Swagger Inspector（免费）： API测试工具，可让您验证您的API并从现有API生成OpenAPI定义
• SwaggerHub（免费和商业）： API设计和文档，为使用OpenAPI的团队构建。

swagger的yaml文件定义

swagger的yaml文件符合Open API规范，详细内容可参考openAPI3.0官网https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md，内容定义了接口的方法名，入参参数类型、是否必须、方法返回值、访问地址等。

OpenAPI文档可以由单个文档组成，也可以根据用户的意愿分为多个相互连接的部分。在后一种情况下，$ref必须在规范中使用字段来引用JSON模式定义中的以下部分。如下为user.yaml的内容。

#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: '2.0'
#必要字段！描述API接口信息的元数据
info: 
  #接口标题
  title: swagger说明文档　
  #接口文档的描述
  description: 学习Swagger
  #版本号
  version: 1.0.0
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．
host: 127.0.0.1
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
basePath: /userapi

#标签组
tags:
  - name: User
    description: 用户模块接口
#指定调用接口的协议，必须是:"http", "https", "ws", "wss"．默认是http.-表示是个数组元素，即schemes接受一个数组参数
schemes:
  - http
  - https

#对应与http协议头request的Accept，调用者可接受类型,默认是*/*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性

#方便swagger-ui测试，先不限制请求格式：浏览器请求默认没有该头信息"Content-Type":"application/json"出现415
#接口能消费的数据类型格式，在postman测试没问题，在swagger-ui界面测试因为默认没有这个content-type请求头所以先取消，正式开发前端人员会写死
#consumes:
#  - application/json

#接口返回的数据类型格式
produces: 
  - application/json
#必要字段!定义可有可操作的API
paths:
  /users:
   #必要字段!定义HTTP操作方法，必须是http协议定义的方法
    get:
      #接口概要
      summary: 查询用户列表
      #接口描述
      description: 查询出所有用户的所有信息
      #接口方法名
      operationId: getUsers
      #标签，方便快速过滤出User相关的接口
      tags:
        - User
      #返回值描述，必要字段
      responses:
        #返回的http状态码
        200:
          description: 所有用户信息或者用户的集合信息
          #描述返回值
          schema:
            $ref: '#/definitions/UsersResponse'
        #执行出错的处理
        default:
          description: 操作异常,执行失败.返回信息描述错误详情