SpringBoot 集成 Swagger Codegen

1. 前言

本节会为大家介绍，如何基于 Spring Boot 集成 Swagger Codegen 到我们的项目中去，以及 Swagger Codegen 快速入门相关知识点，希望通过本节讲解，大家可以对 Swagger Codegen 有进一步的认识。

重点讲解内容：

• 如何将 Swagger Codegen 集成到 SpringBoot 中去；

• Swagger Codegen 快速入门与使用技巧。

2. 如何将 Swagger Codegen 集成到 SpringBoot 中去 ？

因为本套课程使用 Maven 包管理工具构建，所以在集成 Swagger Codegen 时我们需要如下两个步骤：

2.1 第一步：引入 Swagger Codegen 依赖

这里我将依赖放到了下方，同学们可以直接拷贝：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.4.14</version>
</dependency>

等待编辑器下载完成后，没有任何依赖报错，就说明我们已经将 Swagger Codegen 的依赖引入到了 SpringBoot 中去。

2.2 第二步：配置 Swagger Codegen

我们知道，Swagger Codegen 主要的作用，就是生成服务端和客户端的完整代码文件，所以，在将 Swagger Codegen 集成到 Spring Boot 中后，我们首先需要做的就是，对生成服务端和客户端的代码进行规则配置，即我们都需要生成什么样的服务端和客户端代码。

配置服务端和客户端的代码生成规则叫繁琐，所以我们选择常用的几个属性来进行演示。

配置服务端代码生成规则

在 Swagger Codegen 中，配置服务端的代码生成规则，需要用到 yml 配置源文件，所以需要对 yml 配置源的语法有一定了解和掌握，有不清楚的同学请自行查阅相关资料。

swagger: '2.0'
info:
 title: IMooc Swagger-Wiki API
 description: Swagger-Wiki API
 version: 1.0.0
paths:
 /imooct/wiki/swagger:
   get:
     tags:
     - wiki
     operationId: getImoocLesson
     parameters:
     - name: range
       in: query
       type: string
       required: true
     - name: lessonName
       in: query
       type: string
       required: true
     - name: lessonType
       in: query
       type: string
     responses:
       '200':
         description: OK
         schema:
           $ref: '#/definitions/GetImoocLessonResponse'
       default:
         description: default
         schema:
           $ref: '#/definitions/ErrorResponse'

对于以上所使用的属性我们会在本节的后半部分进行详细介绍，这里大家可以先做简单的了解即可。

配置客户端代码生成规则

在 Swagger Codegen 中，客户端的代码规则是通过 json 文件来进行配置的，json 相信大家都很熟悉，这里就不再做相关介绍了。

{
 "apiPackage": "com.imooc.wiki.swagger.api",
 "artifactId": "cmp-imooc-steafan-service",
 "basePackage": "com.steafan.imooc.server",
 "configPackage": "com.steafan.imooc.server.config",
 "dateLibrary": "java8",
 "delegatePattern": true,
 "groupId": "com.steafan.imooc",
 "hideGenerationTimestamp": true,
 "java8": true,
 "language": "spring-boot",
 "modelPackage": "com.imooc.wiki.swagger.api"
}

代码解释：

basePackage ： 用于声明 Swagger Codegen 在生成代码时所扫描的路径。

configPackage ： 用于声明 Swagger Codegen 在生成代码时配置文件所在的目录。

dateLibrary ： 用于声明 Swagger Codegen 在生成代码时所用的语言。

language ： 用于声明 Swagger Codegen 在生成代码时所用的框架语言描述。

modelPackage ：用于声明 Swagger Codegen 在生成代码时项目中实体所在目录。

完成上述配置之后，我们就可以使用 Swagger Codegen 来生成服务端和客户端代码。

2.3 第三步：使用 Swagger Codegen 生成服务端和客户端代码

在将 Swagger Codegen 的依赖引入到 Spring Boot 中去后，我们就可以使用 Maven 自带的命令来将上述配置信息分别生成服务端和客户端代码，命令如下：

首先，将上述配置好的文件利用 Swagger Codegen 来生成服务端和客户端代码

  java -jar swagger-codegen-cli.jar generate -i swagger.yaml -c swaggerConfig.json -l spring -o server

代码解释：

第一行，使用 generate 命令来将配置在 swagger.yaml 文件中的服务端代码进行生成。

第一行，使用 -c 参数，表明使用 json 配置文件，并且该配置文件的名称为 swaggerConfig.json。

第二行，使用 -l 参数，表明客户端所使用的语言为 spring 。

第二行，使用 -o 参数来指定代码最终的存放位置，server 表示将生成的代码存放到名为 server 的文件夹下。

然后我们使用 cd 命令来进到我们生成代码后所存放的目录：

  cd server

最后我们将生成的代码打成 Jar 包:

  mvn package

这是 Maven 自带的打包命令，执行该命令之后，Maven 会默认读取项目中的 pom 文件中配置的打包规则，即 packaging 节点，如果该节点没有配置任何规则，则 Maven 会默认打成 Jar 包 (这里我们配置了 Jar)。

这样我们就可以在项目的 target 目录下，找到我们利用 Swagger Codegen 所生成的服务端和客户端代码的 Jar 包了，我们可以把该 Jar 包放到其他环境中使用，也可以供其他项目使用，这就是我们利用 Swagger Codegen 所生成的服务端和客户端代码的最终使用目的。

3. Swagger Codegen 快速入门与使用技巧

3.1 Swagger Codegen 快速入门

服务端

我们针对以上服务端配置的规则来介绍一下在 Swagger Codegen 服务端中经常使用的一些属性，同学在了解了这些属性之后就可以使用 Swagger Codegen 进行一些服务端代码的生成工作了。

swagger: '2.0'
  info:
   title: IMooc Swagger-Wiki API
   description: Swagger-Wiki API
   version: 1.0.0
  paths:
   /imooct/wiki/swagger:
     get:
       tags:
       - wiki
       operationId: getImoocLesson
       parameters:
       - name: range
         in: query
         type: string
         required: true
       responses:
         '200':
           description: OK
           schema:
             $ref: '#/definitions/GetImoocLessonResponse'

代码解释：

swagger : 指名生成的服务端代码所使用的 Swagger 管理版本，这里只能写 2.0 。

info : 表示 Swagger Codegen 所生成的服务端代码的一些基本描述信息，上述包括 title (头信息) 、 description (文档描述) 、 version (文档版本)。

paths : 表示具体一个接口的路径信息。

get : 表示该接口的 http 请求类型，get 即为 Get 请求，同理 post 即为 Post 请求，以此类推。

tags : 表示该接口所属的分组。

operationId : 表示该接口的名称。

parameters : 表示该接口中的参数信息，上述包括 name (参数名称) 、 in (参数用途) 、type (参数类型) 、 required (参数是否必传，true 表示参数必传，默认为 false )。

responses : 表示该接口的返回信息，这里的 200 表示接口返回状态码，description 代表当接口返回状态码为 200 时的状态码描述信息，schema 中的 ref 属性统一表示当该接口返回 200 时重定向的地址或接下来要发生的动作。

客户端

针对 Swagger Codegen 中客户端代码的配置，在前面已经做了一些较为详细的介绍了，这里我就常用的客户端配置代码给上述内容做一个补充，同学们需要结合着来了解。

{
  "apiPackage": "com.imooc.wiki.swagger.api",
  "artifactId": "cmp-imooc-steafan-service",
  "groupId": "com.steafan.imooc",
  "hideGenerationTimestamp": true,
}

代码解释：

apiPackage : 表示需要生成的客户端代码的包位置。

artifactId 、 groupId : 类似于 Maven 中的依赖坐标，这里表示所生成的客户端代码的坐标信息。

hideGenerationTimestamp : 表示在生成客户端代码之后会隐藏生成代码的时间，这个配置可有可无。

3.2 Swagger Codegen 使用技巧

服务端

我们在生成服务端代码时，不能盲目生成，如果已经有写好的接口文档，那么我们需要按照这个接口文档进行编写和配置，如果没有写好的接口文档，那么我们需要和产品经理进行都次反复的沟通之后才能开始编写和配置服务端信息，这样可以在很大程度上减少服务端配置文件修改的次数，同时也可以提高服务端生成代码的准确性，这点同学们需要注意。

客户端

在生成客户端代码时，我们需要和服务端的开发人员进行详细的沟通，确定代码生成范围以及所需要使用的代码，尽量避免生成多余的、无用的、低价值的代码，这样不仅仅浪费系统资源，同时也浪费了项目开发的时间，这点也需要同学们注意。

4. 小结

本小节从在 SpringBoot 中如何集成 Swagger Codegen 出发，详细介绍了如何在 SpringBoot 中将 Swagger Codegen 进行集成，以及在集成中容易出现的问题。在介绍完 Swagger Codegen 集成 SpringBoot 之后，针对零基础的同学，老师将在 Swagger Codegen 中使用的最多的属性单独拿出来做了介绍，旨在帮助同学们能够快速入门 Swagger Codegen。

各位同学在学习本小节内容时，希望各位可以跟着老师的节奏一行一行地把本小节中所将的代码都动手敲一下，这样可以加深自己对代码的理解程度，在实操时我们不能眼高手低，自己的实践结果才是最重要的。