SpringBoot 集成 Swagger Codegen

1. 前言

本節(jié)會為大家介紹，如何基于 Spring Boot 集成 Swagger Codegen 到我們的項目中去，以及 Swagger Codegen 快速入門相關(guān)知識點，希望通過本節(jié)講解，大家可以對 Swagger Codegen 有進一步的認識。

重點講解內(nèi)容：

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

• Swagger Codegen 快速入門與使用技巧。

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

因為本套課程使用 Maven 包管理工具構(gòu)建，所以在集成 Swagger Codegen 時我們需要如下兩個步驟：

2.1 第一步：引入 Swagger Codegen 依賴

這里我將依賴放到了下方，同學(xué)們可以直接拷貝：

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

等待編輯器下載完成后，沒有任何依賴報錯，就說明我們已經(jīng)將 Swagger Codegen 的依賴引入到了 SpringBoot 中去。

2.2 第二步：配置 Swagger Codegen

我們知道，Swagger Codegen 主要的作用，就是生成服務(wù)端和客戶端的完整代碼文件，所以，在將 Swagger Codegen 集成到 Spring Boot 中后，我們首先需要做的就是，對生成服務(wù)端和客戶端的代碼進行規(guī)則配置，即我們都需要生成什么樣的服務(wù)端和客戶端代碼。

配置服務(wù)端和客戶端的代碼生成規(guī)則叫繁瑣，所以我們選擇常用的幾個屬性來進行演示。

配置服務(wù)端代碼生成規(guī)則

在 Swagger Codegen 中，配置服務(wù)端的代碼生成規(guī)則，需要用到 yml 配置源文件，所以需要對 yml 配置源的語法有一定了解和掌握，有不清楚的同學(xué)請自行查閱相關(guān)資料。

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'

對于以上所使用的屬性我們會在本節(jié)的后半部分進行詳細介紹，這里大家可以先做簡單的了解即可。

配置客戶端代碼生成規(guī)則

在 Swagger Codegen 中，客戶端的代碼規(guī)則是通過 json 文件來進行配置的，json 相信大家都很熟悉，這里就不再做相關(guān)介紹了。

{
 "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 來生成服務(wù)端和客戶端代碼。

2.3 第三步：使用 Swagger Codegen 生成服務(wù)端和客戶端代碼

在將 Swagger Codegen 的依賴引入到 Spring Boot 中去后，我們就可以使用 Maven 自帶的命令來將上述配置信息分別生成服務(wù)端和客戶端代碼，命令如下：

首先，將上述配置好的文件利用 Swagger Codegen 來生成服務(wù)端和客戶端代碼

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

代碼解釋：

第一行，使用 generate 命令來將配置在 swagger.yaml 文件中的服務(wù)端代碼進行生成。

第一行，使用 -c 參數(shù)，表明使用 json 配置文件，并且該配置文件的名稱為 swaggerConfig.json。

第二行，使用 -l 參數(shù)，表明客戶端所使用的語言為 spring 。

第二行，使用 -o 參數(shù)來指定代碼最終的存放位置，server 表示將生成的代碼存放到名為 server 的文件夾下。

然后我們使用 cd 命令來進到我們生成代碼后所存放的目錄：

  cd server

最后我們將生成的代碼打成 Jar 包:

  mvn package

這是 Maven 自帶的打包命令，執(zhí)行該命令之后，Maven 會默認讀取項目中的 pom 文件中配置的打包規(guī)則，即 packaging 節(jié)點，如果該節(jié)點沒有配置任何規(guī)則，則 Maven 會默認打成 Jar 包 (這里我們配置了 Jar)。

這樣我們就可以在項目的 target 目錄下，找到我們利用 Swagger Codegen 所生成的服務(wù)端和客戶端代碼的 Jar 包了，我們可以把該 Jar 包放到其他環(huán)境中使用，也可以供其他項目使用，這就是我們利用 Swagger Codegen 所生成的服務(wù)端和客戶端代碼的最終使用目的。

3. Swagger Codegen 快速入門與使用技巧

3.1 Swagger Codegen 快速入門

服務(wù)端

我們針對以上服務(wù)端配置的規(guī)則來介紹一下在 Swagger Codegen 服務(wù)端中經(jīng)常使用的一些屬性，同學(xué)在了解了這些屬性之后就可以使用 Swagger Codegen 進行一些服務(wù)端代碼的生成工作了。

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 : 指名生成的服務(wù)端代碼所使用的 Swagger 管理版本，這里只能寫 2.0 。

info : 表示 Swagger Codegen 所生成的服務(wù)端代碼的一些基本描述信息，上述包括 title (頭信息) 、 description (文檔描述) 、 version (文檔版本)。

paths : 表示具體一個接口的路徑信息。

get : 表示該接口的 http 請求類型，get 即為 Get 請求，同理 post 即為 Post 請求，以此類推。

tags : 表示該接口所屬的分組。

operationId : 表示該接口的名稱。

parameters : 表示該接口中的參數(shù)信息，上述包括 name (參數(shù)名稱) 、 in (參數(shù)用途) 、type (參數(shù)類型) 、 required (參數(shù)是否必傳，true 表示參數(shù)必傳，默認為 false )。

responses : 表示該接口的返回信息，這里的 200 表示接口返回狀態(tài)碼，description 代表當(dāng)接口返回狀態(tài)碼為 200 時的狀態(tài)碼描述信息，schema 中的 ref 屬性統(tǒng)一表示當(dāng)該接口返回 200 時重定向的地址或接下來要發(fā)生的動作。

客戶端

針對 Swagger Codegen 中客戶端代碼的配置，在前面已經(jīng)做了一些較為詳細的介紹了，這里我就常用的客戶端配置代碼給上述內(nèi)容做一個補充，同學(xué)們需要結(jié)合著來了解。

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

代碼解釋：

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

artifactId 、 groupId : 類似于 Maven 中的依賴坐標(biāo)，這里表示所生成的客戶端代碼的坐標(biāo)信息。

hideGenerationTimestamp : 表示在生成客戶端代碼之后會隱藏生成代碼的時間，這個配置可有可無。

3.2 Swagger Codegen 使用技巧

服務(wù)端

我們在生成服務(wù)端代碼時，不能盲目生成，如果已經(jīng)有寫好的接口文檔，那么我們需要按照這個接口文檔進行編寫和配置，如果沒有寫好的接口文檔，那么我們需要和產(chǎn)品經(jīng)理進行都次反復(fù)的溝通之后才能開始編寫和配置服務(wù)端信息，這樣可以在很大程度上減少服務(wù)端配置文件修改的次數(shù)，同時也可以提高服務(wù)端生成代碼的準(zhǔn)確性，這點同學(xué)們需要注意。

客戶端

在生成客戶端代碼時，我們需要和服務(wù)端的開發(fā)人員進行詳細的溝通，確定代碼生成范圍以及所需要使用的代碼，盡量避免生成多余的、無用的、低價值的代碼，這樣不僅僅浪費系統(tǒng)資源，同時也浪費了項目開發(fā)的時間，這點也需要同學(xué)們注意。

4. 小結(jié)

本小節(jié)從在 SpringBoot 中如何集成 Swagger Codegen 出發(fā)，詳細介紹了如何在 SpringBoot 中將 Swagger Codegen 進行集成，以及在集成中容易出現(xiàn)的問題。在介紹完 Swagger Codegen 集成 SpringBoot 之后，針對零基礎(chǔ)的同學(xué)，老師將在 Swagger Codegen 中使用的最多的屬性單獨拿出來做了介紹，旨在幫助同學(xué)們能夠快速入門 Swagger Codegen。

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