Swagger 使用
Swagger 有什么用？
Swagger 是一個流行的API開發框架，這個框架以“開放API聲明” （OpenAPI Specification，OAS） 為基礎，
對整個 API 的開發周期都提供了相應的解決方案，是一個非常龐大的項目（包括設計、編碼和測試，幾乎支持所有語言）。
Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。
總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。
文件的方法，參數和模型緊密集成到服務器端的代碼，允許 API 來始終保持同步。 Swagger 讓部署管理和使用功能強大的 API 從未如此簡單。
SpringBoot 與 Swagger2
由于 JAVA 的強大的注解功能，我們使用 SpringBoot 來結合 Swagger2 ，在使用起來非常簡單.
第一步：新建 SpringBoot 項目，引入依賴.
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
上面兩個依賴的作用：
springfox-swagger2 依然是依賴 OSA 規范文檔，也就是一個描述 API 的 json 文件，而這個組件的功能就是幫助我們自動生成這個 json 文件
SpringFox 大致原理：
springfox的大致原理就是，在項目啟動的過程中，Spring 上下文在初始化的過程，
框架自動根據配置加載一些 Swagger 相關的 bean 到當前的上下文中，并自動掃描系統中可能需要生成 API 文檔那些類，
并生成相應的信息緩存起來。如果項目MVC控制層用的是 SpringMvc 那么會自動掃描所有 Controller 類，并生成對應的文檔描述數據.
該數據是json格式，通過路徑：項目地址 /v2/api-docs可以訪問到該數據，然后 SwaggerUI根據這份數據生成相應的文檔描述界面。
因為我們能拿到這份數據，所以我們也可以生成自己的頁面。
springfox-swagger-ui 就是將這個 json 文件解析出來，用一種更友好的方式呈現出來。
由于 Spring 的流行，Marty Pitt 編寫了一個基于 Spring 的組件 swagger-springmvc，用于將 Swagger 集成到 SpringMVC 中來。
第二步：創建 API
@RestController
public class UserController {
@RequestMApping("/hello",method = RequestMethod.GET)
public String hello(){
return "hello";
}
}
配置 Swagger2
現在 Swagger2 還不能為我們生成 API 文檔，因為我們還沒有對它進行配置。
我們需要創建一個配置類，進行如下配置：
@Configuration
@EnableSwagger2
public class SwaggerConfig{
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.itguang.springbootswaggerdemo1.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構建RESTful API")
.description("rest api 文檔構建利器")
.termsOfServiceUrl("http://blog.csdn.net/itguangit")
.contact("itguang")
.version("1.0")
.build();
}
}
springfox 為我們提供了一個 Docket（摘要的意思）類，我們需要把它做成一個 Bean 注入到 spring 中。顯然，我們需要一個配置文件，并通過一種方式（顯然它會是一個注解）告訴程序，這是一個 Swagger 配置文件。
springfox 允許我們將信息組合成一個 ApiInfo 的類，作為構造參數傳給 Docket（當然也可以不構造這個類，而直接使用 Null，但是你的這個 API 就太 low 了）。
搞定
現在我們要做的配置已經能滿足一個生成 API 文檔的基本要求了，讓我們啟動項目，訪問 http://localhost/swagger-ui.html
會看到如下界面:
這是 Swagger-ui 為我們生成的界面.
Swagger2 注解使用
接下來我們就要好好研究下 springfox-swagger2 給我們提供的注解了.
我們新建一個 Controller，用來對 User 類進行增刪改查常用操作。
@RestController
@RequestMapping(value = "/user", produces = APPLICATION_JSON_VALUE) //配置返回值 application/json
@Api(description = "用戶管理")
public class HelloController {
ArrayList<User> users = new ArrayList<>();
@ApiOperation(value = "獲取用戶列表", notes = "獲取所有用戶信息")
@RequestMapping(value = {""}, method = RequestMethod.GET)
public List<User> hello() {
users.add(new User("邏輯", "luoji"));
users.add(new User("葉文杰", "yewenjie"));
return users;
}
}
可以看到我們在 Controller 上使用了 @Api(description = "用戶管理") 注解，在方法上使用了 @ApiOperation(value = "獲取用戶列表", notes = "獲取所有用戶信息") 注解。
這會產生什么樣的效果呢? 我們可以再次訪問下試試看：
可以看到我們紅框裱起來的地方發生了改變，并且神奇的是它還自動判斷出了我們的返回類型：
[
{
"age": 0,
"email": "string",
"enabled": true,
"id": "string",
"password": "string",
"username": "string"
}
]
但是我們如果想選擇性的忽略某個字段，而不是把 User 類中的所有字段暴露出去呢?別著急，我們可以使用另一個注解：@ApiModelProperty(hidden = true)。此注解可以作用在字段或者方法上，只要 hidden 屬性為 true ，該字段或者方法就不會被生成 API 文檔。
@Data
public class User {
private String id;
private String username;
@ApiModelProperty(hidden = true)
private String password;
private String email;
private Integer age;
private Boolean enabled;
}
我們有意忽略了 password 字段，再次刷新瀏覽器，會看到：
確實 password 字段不見了。
接下來我們在模擬一個創建用戶的 API：
@ApiOperation(value = "創建用戶", notes = "根據User對象創建用戶")
@RequestMapping(value = "/create", method = RequestMethod.POST)
public User postUser(User user) {
return user;
}
可以看到我們需要客戶端傳給我們一個 User 對象，用來創建和該用戶，這里我們什么也不做，只是把接受到的 User 對象返回給客戶端，來表示創建成功。
我們刷新瀏覽器看下：
可以看到請求參數并不是讓我們很滿意啊，第一沒有字段說明，第一有些字段在創建用戶時我們并不需要啊，還是不要著急，我們也有辦法解決：
@ApiModelProperty(hidden = true) private String id; @ApiModelProperty(value = "用戶名") private String username; @ApiModelProperty(value = "密碼") private String password; @ApiModelProperty(value = "郵箱") private String email; @ApiModelProperty(hidden = true) private Integer age; @ApiModelProperty(hidden = true) private Boolean enabled;
我們在User對象的字段上添加 上面的注解： @ApiModelProperty(hidden = true) 和 @ApiModelProperty(value = "用戶名")。
value 屬性指明了該字段的含義(描述 Description)，再次刷新瀏覽器試試：
怎么樣，是不是很簡單。
下面我們看看如何傳遞參數。添加一個方法，根據 id 獲取用戶信息：
@ApiOperation(value = "獲取用戶詳細信息", notes = "根據url的id來獲取用戶詳細信息")
@RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
public User getUser(@PathVariable(value = "id") String id) {
return new User(id, "itguang", "123456");
}
刷新瀏覽器，可以看到：
我們需要客戶端傳入一個參數 id，現在我們要給 id 這個參數一個說明(Description)，該咋辦呢? 還是不要著急，很簡單像下面這樣即可：
@ApiOperation(value = "獲取用戶詳細信息", notes = "根據url的id來獲取用戶詳細信息")
@RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
public User getUser(@ApiParam(value = "用戶id", required = true) //[注意] @ApiParam與 Controller中方法并列使用,也可以省略的
@PathVariable(value = "id") String id) {
return new User(id, "itguang", "123456");
}
我們添加了 @ApiParam(value = "用戶id", required = true) 這個注解，需要注意的是，這個注解方法的參數前面，不能直接用在方法上面。
再次刷新瀏覽器：
常用注解說明：
通過上面的了解，我們大概已經會使用 Swagger2 了，但我們只介紹了一些簡單常用的注解。
下面我們系統的總結一下：
Swagger2 基本使用(重點加粗顯示)：
@Api：描述類/接口的主要用途
@ApiOperation：描述方法用途
@ApiImplicitParam：描述方法的參數
@ApiImplicitParams：描述方法的參數(Multi-Params)
可以在上面 創建用戶的方法上添加 @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")試試看.
@ApiParam：請求屬性
@ApiIgnore：忽略某類/方法/參數的文檔
注意與 @ApiModelProperty(hidden = true)不同， @ApiIgnore 不能用在模型數據上
@ApiResponse：響應配置
如 @ApiResponse(code = 400, message = "無效的用戶信息") ，注意這只是在 生成的 Swagger 文檔上有效，不要和實際的客戶端調用搞混了.
通常我們都是統一JSON返回，用不到這個注解
@ApiResponses：響應集配置
@ResponseHeader：響應頭設置
例如: @ResponseHeader(name="head1",description="response head conf")
@ApiModel：標識請求/相應模型
@ApiModelProperty：添加和操作模型屬性的數據
我想看中文的
經過上面的介紹，你應該已經會使用 Swagger2 了。但是對于有些人來說，看上面的英文表示很難受，有沒有中文的?
有!
根據官方文檔上的提示，在 SpringBoot 下更換界面和語言還是很簡單的，首先我們需要對 SpringBoot 的資源目錄有個了解：
Spring Boot 默認“約定”從資源目錄的這些子目錄讀取靜態資源：
src/main/resources/META-INF/resources src/main/resources/static （推薦） src/main/resources/public
舉個栗子：現在static目錄下有一張圖片，kumamon.jpg，訪問地址是 http://localhost:8080/img/kumamon.jpg
注：若不同靜態目錄含有相同路徑圖片，則按上述優先級，即 META-INF/resources 目錄優先級最高。
了解了 SpringBoot 的資源目錄的優先級，我們來看看之前引入的 springfox-swagger-ui 這個包，打開 Maven 依賴找到它：
展開如下所示：
還記得我們之前為什么瀏覽器輸入 http://localhost/swagger-ui.html 就會看到一個 Swagger 的頁面嗎，沒錯就是這里啦。其中 swagger-ui.html 就是首頁。
打開看下：
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Swagger UI</title> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/> <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/> <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/JavaScript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script> </head> <body class="swagger-section"> <div id='header'> <div class="swagger-ui-wrap"> <a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="webjars/springfox-swagger-ui/images/logo_small.png" /><span class="logo__title">swagger</span></a> <form id='api_selector'> <div class='input'> <select id="select_baseUrl" name="select_baseUrl"/> </div> <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div> <div id='auth_container'></div> <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div> </form> </div> </div> <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </body> </html>
看不懂? 好吧，看不懂也沒關系，我們想要漢化該咋辦呢?
我們也不能直接在這里修改源碼啊，還記得我們前面提到的 Spring boot 資源目錄的優先級嗎? 沒錯，我們只需要在記得項目下創建 META-INF 這個資源目錄就行啊。
SpringBoot 默認會把我們項目的 src/main/resources/META-INF/resources覆蓋其它的依賴下的文件。
開始漢化
創建 資源目錄 src/main/resources/META-INF/resources，如下：
swagger-ui.html 的內容如下：
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>itguang</title> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/> <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/> <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/> <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/> <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script> <!--國際化操作：選擇中文版 --> <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script> </head> <body class="swagger-section"> <div id='header'> <div class="swagger-ui-wrap"> <a id="logo" href="http://swagger.io"> <img class="logo__img" alt="swagger" height="30" width="30" src="webjars/springfox-swagger-ui/images/logo_small.png" /> <span class="logo__title">swagger</span></a> <form id='api_selector'> <div class='input'> <select id="select_baseUrl" name="select_baseUrl"></select> </div> <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div> <div id='auth_container'></div> <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div> </form> </div> </div> <div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div> <div id="swagger-ui-container" class="swagger-ui-wrap"></div> </body> </html>
其實我們只添加了兩行代碼：
<!--國際化操作：選擇中文版 --> <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>
zh-cn.js 文件內容如下：
'use strict';
/* jshint quotmark: double */
window.SwaggerTranslator.learn({
"Warning: Deprecated":"警告：已過時",
"Implementation Notes":"實現備注",
"Response Class":"響應類",
"Status":"狀態",
"Parameters":"參數",
"Parameter":"參數",
"Value":"值",
"Description":"描述",
"Parameter Type":"參數類型",
"Data Type":"數據類型",
"Response Messages":"響應消息",
"HTTP Status Code":"HTTP狀態碼",
"Reason":"原因",
"Response Model":"響應模型",
"Request URL":"請求URL",
"Request Headers":"請求頭",
"Response Body":"響應體",
"Response Code":"響應碼",
"Response Headers":"響應頭",
"Hide Response":"隱藏響應",
"Headers":"頭",
"Try it out!":"試一下！",
"Show/Hide":"顯示/隱藏",
"List Operations":"顯示操作",
"Expand Operations":"展開操作",
"Raw":"原始",
"can't parse JSON. Raw result":"無法解析JSON. 原始結果",
"Example Value":"示例",
"Click to set as parameter value":"點擊設置參數",
"Model Schema":"模型架構",
"Model":"模型",
"apply":"應用",
"Username":"用戶名",
"Password":"密碼",
"Terms of service":"服務條款",
"Created by":"創建者",
"See more at":"查看更多：",
"Contact the developer":"聯系開發者",
"api version":"api版本",
"Response Content Type":"響應Content Type",
"Parameter content type:":"參數類型:",
"fetching resource":"正在獲取資源",
"fetching resource list":"正在獲取資源列表",
"Explore":"瀏覽",
"Show Swagger Petstore Example Apis":"顯示 Swagger Petstore 示例 Apis",
"Can't read from server. It may not have the appropriate access-control-origin settings.":"無法從服務器讀取。可能沒有正確設置access-control-origin。",
"Please specify the protocol for":"請指定協議：",
"Can't read swagger JSON from":"無法讀取swagger JSON于",
"Finished Loading Resource Information. Rendering Swagger UI":"已加載資源信息。正在渲染Swagger UI",
"Unable to read api":"無法讀取api",
"from path":"從路徑",
"server returned":"服務器返回"
});
你也可以自己定義中文名稱啦。
漢化搞定.
到此，Swagger 的漢化工作已經做完，是不是很簡單，重新啟動項目，訪問
http://localhost/swagger-ui.html
就可以看到文檔已經完全漢化啦：
小結:
好了，關于 Swagger2 在項目中的使用介紹就到這里。
end：如果你覺得本文對你有幫助的話，記得關注點贊轉發，你的支持就是我更新動力。
如果您有不同的看法，歡迎在評論區留言與我們一起討論
