Swagger Codegen生成接口

左丘源

2023-12-01

前言：好久没写博客了，年底到前段日子很忙，加班比较多，加上本人不喜欢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: 操作异常,执行失败.返回信息描述错误详情
          schema:
            $ref: '#/definitions/ExceptionResponse'
                
    #针对于同一个url定义两个不同的方法，表示两个接口
    post:
      #接口概要
      summary: 新增一个用户
      #接口描述
      description: 新增一个用户
      operationId: addUser
      #标签，方便快速过滤出User相关的接口
      tags:
        - User
      #请求参数
      parameters:
          #参数key
        - name: user
          #传递方法，formData表示表单传输，还有query表示url拼接传输，path表示作为url的一部分
          #body表示http头承载参数(body只能有一个,有body不能在有其他的)
          in: body
          #参数描述
          description: 新增用户信息
          #参数是否必要，默认false
          required: true
          schema: 
            $ref: '#/definitions/User'
      responses:
        #返回的http状态码
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
            $ref: '#/definitions/   '
        #执行出错的处理
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
            $ref: '#/definitions/ExceptionResponse'
  /query:           
    get: 
      summary: 根据用户id查询用戶信息
      description: 查询用戶信息
      operationId: getUser
      tags:
        - User
      parameters: 
        - name: id
          in: query
          description: 根据id查询用戶信息，是唯一标识
          required: true
          type: integer
      responses:
        200:
          description: 用户的信息
          schema:
              $ref: '#/definitions/User'
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
            $ref: '#/definitions/ExceptionResponse' 
              
  /user/{id}:
    #{id}表示id为请求参数，例如/users/1,/users/2都是对该API的请求，此时id即为１和2
    #上面接口中定义了{id}，则参数列表中必须包含参数id,并且请求类型in为path
    #http定义的delete方法,删除一个资源
    delete:
      summary: 删除用户
      description: 删除某个用户的信息，被删除的用户将无法登陆
      operationId: deleteUser
      parameters:
        - name: id
          in: path
          type: integer
          required: true
          description: 用户的唯一标示符
      tags:
        - User
      responses:
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
              $ref: '#/definitions/SuccessResponse'
        default:
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              $ref: '#/definitions/ExceptionResponse'
              
    #http定义的put方法，表示修改一个资源
    put: 
      summary: 用户信息修改
      description: 修改用户信息(用户名别名)
      operationId: updateUser
      parameters: 
        - name: id
          in: path
          description: 用户名,要修改的数据的唯一标识符
          required: true
          type: integer
        - name: user
          in: body
          description: 新的用户信息
          required: true
          type: string
          schema: 
            $ref: '#/definitions/User'
      tags:
        - User
      responses:
        200:
          description: 通过返回值来标示执行结果　返回true表示执行成功
          schema:
             $ref: '#/definitions/SuccessResponse'
        default:
         #描述错误信息
          description: 操作异常,执行失败.返回信息描述错误详情
          schema:
              $ref: '#/definitions/ExceptionResponse'
  
definitions:
  User:
    #值类型
    type: object
    #定义属性
    properties:
    #属性名
      userId: 
        #参数类型，可选的包括array,integer,boolean,string.使用array必须使用items
        type: integer
        #描述
        description: 用户的唯一id
      userName:
        type: string
        description: 用户名
      gender:
        type: string
        description: 性別
      age:
        type: integer
        format: int32
        description: 年齡
      dateOfBirth: 
        type: string
        format: date
        description: 生日
        
  AddUserRequest:
    #值类型
    type: object
    #定义属性
    properties:
    #属性名
      userName:
        type: string
        description: 用户名
      gender:
        type: string
        description: 性別
      age:
        type: integer
        format: int32
        description: 年齡
      dateOfBirth: 
        type: string
        format: date
        description: 生日
        
  UsersResponse: 
    properties:
      users: 
        description: 返回的user列表
        #针对array,每个条目的格式,type定义为array．必要填写items
        type: array
        items: 
          #引用在definitions下定义的Users
          $ref: "#/definitions/User"
  
  ExceptionResponse:
    type: object
    properties:
      code:
        type: string
        description: 错误码
      msg:
        type: string
        description: 错误信息
    
  SuccessResponse:
    type: object
    properties:
      status:
      #类型
        type: boolean
        #描述
        description: 是否成功

其中parameters属性解释
name: limit //参数的名字
in: query //描述参数以什么方式怎么传递到后台
type: integer //类型
required: false //是否必须
default: 20 //默认
minimum: 1 //最小值
maximum: 100 //最大值
description: The numbers of items to return. //参数的描述

关于in属性的解释

query ：通过地址栏传参：/users?id=1
path ：通过restful风格传参：/users/{id}
head： X-MyHeader: Value：没用过
body ：请求体：只能由一个body上述案例用到了可以参考。

根据yaml文件自动生成代码：

1、下载生成器jar包：

我使用的是swagger-codegen-cli-2.4.5.jar这个版本，现在是最新的，读者可根据maven仓库下载列表下载较新的：https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/

2、打开CMD命令行窗口，进入jar包的存放目录，执行命令

生成client代码使用参数-l java

比如我的jar目录在D:\hl\mvp目录下：

java -jar swagger-codegen-cli-2.4.5.jar generate -i D:\hl\mvp\user.yaml -c D:\hl\mvp\config-user.json -l spring-o demo/java

命令解释：

-i ：指定swagger描述文件的路径，url地址或路径文件，该参数为必须
-l ：指定生成客户端代码的语言，该参数为必须，java代表原生的，spring或spring-boot代表spring整合的，我这里用springboot项目接口，所以使用-l spring
-o：指定生成文件的位置(生成文件根目录默认当前目录)
-c ： json格式的配置文件的路径

config-user.json是描述生成的文件的目录结构，代码一些基础信息：

{
 //  生成***Api.java文件包名
	"apiPackage": "com.formssi.mvp.controller.api",
 //指定生成pom.xml的artifactId的值
	"artifactId": "mvp",
//基础路径
	"basePackage": "com.formssi.mvp",
	"dateLibrary": "java8",
//允许使用标签组
	"useTags": true,
	"delegatePattern": true,
	"groupId": "com.formssi",
	"hideGenerationTimestamp": true,
	"java8": true,
	"dateLibrary": "java8-localdatetime",
//和上面命令-l参数一样，同时写命令的优先！！，spring的更简单，
	"language": "spring",
  // 生成的数据模型Java文件包名
	"modelPackage": "com.formssi.mvp.model",
  // 生成的swagger配置文件的包名
	"configPackage": "com.formssi.mvp.config"
}

配置文件其他参数：
“developerName”: “hl”, // 开发者姓名
“developerEmail”: “”, // 开发者邮件
“developerOrganization”: “”, // 开发者组织
“invokerPackage”: “com.mvp.test”, //项目包名

生成的这些文件里，src文件下的文件和pom.xml文件是对我们最有用的。

3、复制配置类、配置文件、接口API类并重写、实体类等有用信息到项目自己完成业务逻辑即可。

4、附上swagger接口常用注解说明

 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiParam：单个参数描述
 @ApiModel：用对象来接收参数
 @ApiProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述
 @ApiIgnore：使用该注解忽略这个API
 @ApiError ：发生错误返回的信息
 @ApiImplicitParam：一个请求参数
 @ApiImplicitParams：多个请求参数