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。

各位同學在學習本小節內容時，希望各位可以跟著老師的節奏一行一行地把本小節中所將的代碼都動手敲一下，這樣可以加深自己對代碼的理解程度，在實操時我們不能眼高手低，自己的實踐結果才是最重要的。