api文檔在線自動生成工具Swagger推薦（含Spring Cloud集成版）

01-31

今日頭條作者：不宅的技術男

不宅的技術男www.toutiao.com

一、Swagger是什麼
二、Swagger功能演示
三、Swagger 與Spring Cloud 集成

Swagger是什麼

Swagger 是一款線自動生成+測試功能插件，基於RESTFUL介面調動。

開發人員經常會遇到寫介面文檔的工作，一般都是word文檔，帶來書寫麻煩、維護麻煩的問題，比如改了源代碼忘了更新文檔、解釋不明確帶來歧義、無法在線嘗試等等。swagger就是為了解決這些問題而產生的。

Swagger是最受歡迎的REST APIs文檔生成工具之一，主要有以下幾個原因：

可以快速生成API調用介面，提供完整的介面輸入輸出參數說明，方便調用者調試。
可以方便與多平台集成
文件可以在許多不同的平台上從代碼注釋中自動生成。
Swagger 社區活躍，項目發展有保障。

Swagger 文檔提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 信息，也可以通過代碼注釋方式描述。本文以代碼注釋方式演示。

Swagger功能演示

1、代碼邏輯

@api，用在類上，用於解釋整個類。
@apioperation，用於方法上，value是概要介紹方法作用，notes是詳細說明。

2、Swagger UI 展示

（api被調用執行結果在線展示）

Swagger 與Spring Cloud 集成

1、下載jar包

2、本地安裝

cd spring-boot-starter-swagger2
mvn install

3、在spring-cloud的項目中，添加maven依賴

pom.xml

<dependency>
<groupId>com.github.ganity</groupId>

<artifactId>spring-boot-starter-swagger2</artifactId>
<version>1.0.1</version>
</dependency>

4、Spring Cloud 配置

application.yml or application.properties

swagger:
enable: true #if enable swagger
group: item #the api group name
title: item-title #the title
description: item description
version: v1.10

contact-name: ganily
base-package: video.lark.mall.item.service #the base package for RequestHandlerSelectors default all the package
license: Apache License Version 2.0

5、Spring Cloud 服務重啟

訪問 swagger ui 頁面

結束

歡迎大家多交流，謝謝！

今日頭條作者：不宅的技術男

不宅的技術男www.toutiao.com