SpringBoot 集成 Swagger Editor

1. 前言

本節(jié)會(huì)為大家介紹，如何基于 Spring Boot 集成 Swagger Editor 到我們的項(xiàng)目中去，以及 Swagger Editor 快速入門相關(guān)知識(shí)點(diǎn)，希望通過本節(jié)講解，大家可以對(duì) Swagger Editor 有進(jìn)一步的認(rèn)識(shí)。

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

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

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

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

集成前的問題

因?yàn)楸咎渍n程使用 Maven 包管理工具構(gòu)建，所以在集成之前需要我們先將 Swagger Editor 的依賴引入到項(xiàng)目中去，但是很不幸，Swagger Editor 官方并沒有提供對(duì) Maven 的支持，所以我們就不能通過 Maven 的方式將 Swagger Editor 集成進(jìn)來。

難道就沒有辦法將 Swagger Editor 與 SpringBoot 結(jié)合使用了嗎 ？

俗話說，方法總比困難多，所以這里我們另辟蹊徑，通過使用配置 yml 文件的方式將 Swagger Editor 集成進(jìn)來，話不多說，我們直入正題。

2.1 第一步：修改 SpringBoot 項(xiàng)目配置文件

我們都知道，在 SpringBoot 項(xiàng)目中，一般的項(xiàng)目配置文件是如下圖所示的 applicaiton.properties 文件：

applicaiton.properties 文件是傳統(tǒng)的項(xiàng)目配置文件，無論使用 Spring 的哪種框架，我們都可以在項(xiàng)目中使用 applicaiton.properties 文件，但是這種文件有一種弊端，就是我們項(xiàng)目的配置信息在該文件中顯示的有點(diǎn)亂，不利于開發(fā)人員維護(hù)，通常一行配置語句會(huì)顯得很長(zhǎng)，降低了項(xiàng)目配置文件的可閱讀性。

正如此，在經(jīng)過時(shí)代變遷之后，終于迎來了 YAML 配置源文件的到來，YAML 文件不單單只是一種平臺(tái)上的配置源文件，他可以支持 Java 、 Python 、 PHP 等主流語言使用，并且各種語言平臺(tái)都有對(duì)應(yīng)的轉(zhuǎn)換配置語法對(duì)應(yīng)關(guān)系表，編寫起來簡(jiǎn)單方便，且利于閱讀。

將 applicaiton.properties 文件 修改為 YMAL 配置源文件的方式非常簡(jiǎn)單，我們只需要將 applicaiton.properties 文件的后綴 .properties 修改為 .yml 就可以了。

在修改完之后，我們就不能使用 applicaiton.properties 文件的語法了，我們需要使用 YMAL 配置源文件的語法才行。

2.2 第二步：配置 Swagger Editor 源文件

在集成 Swagger Editor 到 SpringBoot 中時(shí)，為什么我們需要將 SpringBoot 項(xiàng)目的配置文件 applicaiton.properties 來修改成 YAML 配置源文件呢 ？這是因?yàn)槲覀兊?Swagger Editor 只支持以 .yml 文件格式結(jié)尾的配置文件來編寫 Swagger Editor ，這也是我一再?gòu)?qiáng)調(diào) YAML 配置源文件的原因。

在修改好配置源文件之后，接下來我們需要編寫配置源文件，并且在編寫完配置源文件之后，我們需要將該配置源文件進(jìn)行重命名，重命名的規(guī)則一般都是項(xiàng)目名稱 + Swagger Editor + 配置源文件版本號(hào)。

簡(jiǎn)易配置 Swagger Editor 源文件

Swagger Editor 的配置源文件我們?cè)?Spring Boot 集成 Swagger Codegen 小節(jié)中做了簡(jiǎn)短的介紹：就是我們?cè)谂渲?Swagger Codegen 服務(wù)端代碼生成規(guī)則那里的服務(wù)端代碼其實(shí)就是 Swagger Editor 配置源文件的一部分，也就是說Swagger Codegen 服務(wù)端的代碼生成規(guī)則是通過 Swagger Editor 配置源文件來實(shí)現(xiàn)的。

所以，在掌握了 Swagger Editor 的基本語法和使用技巧之后，我們就可以在編寫好 Swagger Editor 配置源文件之后來生成我們項(xiàng)目的服務(wù)端代碼，可謂是一舉兩得，這也是 Swagger 官方為我們所考慮的一方面。

還是那句話，在 Swagger Editor 中，配置 Swagger Editor 需要對(duì) yml 配置源文件有一定的了解和使用，所以，有不清楚的同學(xué)請(qǐng)自行查閱相關(guān)資料。

接下來我們通過 Swagger Editor 官方的 Demo 來為大家配置 Swagger Editor 。

Swagger Editor 基本配置信息

swagger: "2.0"
info:
 description: "This is a sample server Petstore server. You can find out more about Swagger at http://swagger.io or on irc.freenode.net, #swagger. For this sample, you can use the api key special-key to test the authorization filters."
 version: "1.0.0"
 title: "Swagger Petstore"
 termsOfService: "http://swagger.io/terms/"
 contact:
   email: "apiteam@swagger.io"
 license:
   name: "Apache 2.0"
   url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
 name: "pet"
 description: "Everything about your Pets"
 externalDocs:
 description: "Find out more"
 url: "http://swagger.io"
schemes:
 "https"
 "http"

Swagger Editor 接口配置信息

paths:
  /pet:
    post:
      tags:
       - "pet"
      summary: "Add a new pet to the store"
      description: ""
      operationId: "addPet"
      consumes:
        "application/json"
        "application/xml"
      produces:
        "application/xml"
        "application/json"
      parameters:
        in: "body"
        name: "body"
        description: "Pet object that needs to be added to the store"
        required: true
        schema:
          $ref: "#/definitions/Pet"
    responses:
      "405":
        description: "Invalid input"

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

2.3 第三步：使用 Swagger Editor 生成 Swagger-UI 界面

在配置好 Swagger Editor 基本配置信息和 Swagger Editor 接口配置信息之后，我們就可以在項(xiàng)目中生成 Swagger-UI 界面了。

我們生成 Swagger-UI 界面需要依賴 http-server ，我們?cè)诰庉嬈鞯目刂婆_(tái)中輸入以下命令即可：

  http-server swagger-editor .yml文件路徑

即我們?yōu)?Swagger Editor 指定需要使用的 .yml 配置源文件即可，生成后的界面如下圖所示。

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

接下來，我們針對(duì)上述 Swagger Editor 配置源文件中的屬性來為大家介紹每個(gè)屬性都代表什么意思，都用來做什么，以及在使用 Swagger Editor 時(shí)的一些使用技巧和注意事項(xiàng)。

3.1 Swagger Editor 快速入門

Swagger Editor 基本配置信息

swagger: "2.0"
info:
  description: "Swagger Editor Demo"
  version: "1.0.0"
  title: "Swagger Petstore"
  termsOfService: "http://swagger.io/terms/"
  contact:
    email: "apiteam@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "petstore.swagger.io"
basePath: "/v2"
tags:
  name: "pet"
  description: "Everything about your Pets"
  externalDocs:
  description: "Find out more"
  url: "http://swagger.io"
schemes:
  "https"
  "http"

代碼解釋：

swagger : 指名所使用的 Swagger 管理版本，這里只能寫 2.0 。

info : 表示 Swagger Codegen 所生成的 Swagger-UI 界面的一些基本描述信息，上述包括 title(頭信息) 、 description(文檔描述) 、 version(文檔版本) 、termsOfService(服務(wù)團(tuán)隊(duì)) 、 contact(聯(lián)系人) 、 license(協(xié)議或條款)。

host : 表示生成的 Swagger-UI 所在的主機(jī)，即 Swagger-UI 界面生成之后是放在什么位置的。

basePath : 表示訪問 Swagger-UI 生成界面的具體路徑。

tags : 表示對(duì) Swagger-UI 文檔中的接口進(jìn)行分組。

tags-description : 對(duì)接口分組添加描述信息。

tags-externalDocs : 指定接口分組額外的說明文檔，這里沒有指定。

tags-url : 表示對(duì)該接口分組添加額外的描述信息地址。

schemes : 表示整個(gè) Swagger-UI 界面上的接口所使用的網(wǎng)絡(luò)協(xié)議，這里指名可以使用 http 和 https 網(wǎng)絡(luò)協(xié)議。

Swagger Editor 接口配置信息

由于篇幅有限，Swagger Editor 接口配置信息部分的屬性介紹在 SpringBoot 集成 Swagger Codegen 這一小節(jié)中有詳細(xì)的說明，同學(xué)們可以去該小節(jié)了解。

3.2 Swagger Editor 使用技巧

我們?cè)谑褂?Swagger Editor 時(shí)，一般都是在沒有借口文檔的情況下進(jìn)行，所以這就要求我們對(duì)接口所開展的業(yè)務(wù)有很清晰的了解才行。

在 Swagger Editor 中，我們會(huì)對(duì)不同屬性編寫不同的描述信息，而涉及到名字的屬性一定要注意，例如：title 屬性，在對(duì)這一類型屬性進(jìn)行描述時(shí)，我們應(yīng)該根據(jù)項(xiàng)目需求文檔來進(jìn)行描述，不能自己隨意起名字，只有按照項(xiàng)目需求文檔來描述的 Swagger Editor 屬性才能說是準(zhǔn)確的，是服務(wù)于當(dāng)前項(xiàng)目的。

即使我們把 Swagger Editor 引入到了 SpringBoot 項(xiàng)目中去，但是如果想要運(yùn)行 Swagger Editor ，我們還是要依賴于 http-server ，因?yàn)?Maven 并沒有提供對(duì) Swagger Editor 的支持服務(wù)。

4.小結(jié)

本小節(jié)對(duì)在基于 SpringBoot 環(huán)境下如何集成 Swagger Editor 進(jìn)行了詳細(xì)的介紹，通過對(duì)分解的集成實(shí)現(xiàn)思路的詳細(xì)介紹以及為何要采用該種實(shí)現(xiàn)思路的原因都做了詳細(xì)的介紹和補(bǔ)充說明，在文章最后還詳細(xì)闡述了 Swagger Editor 在實(shí)際項(xiàng)目開發(fā)中使用的一些注意事項(xiàng)，旨在幫助大家在了解了 Swagger Editor 基本定義之后可以快速入門 Swagger Editor。

在集成 Swagger Editor 時(shí)，還需要注意 Swagger Editor 與 Swagger Codegen 之間的共同點(diǎn)與不同點(diǎn)，注意區(qū)分和體會(huì)他們的應(yīng)用場(chǎng)景和使用目的，這樣在實(shí)際開發(fā)中才能根據(jù)不同場(chǎng)景來選擇合適的工具來完成工作。