【Java】Swagger快速入門

時間 2019-11-06

標籤 Java swagger 快速入門欄目 Java 简体版

原文原文鏈接

Swagger 簡介

　　Swagger 是一套基於 OpenAPI 規範構建的開源工具，能夠幫助咱們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了如下三個部分：css

Swagger Editor：基於瀏覽器的編輯器，咱們可使用它編寫咱們 OpenAPI 規範。
Swagger UI：它會將咱們編寫的 OpenAPI 規範呈現爲交互式的 API 文檔，後文我將使用瀏覽器來查看而且操做咱們的 Rest API。
Swagger Codegen：它能夠經過爲 OpenAPI（之前稱爲 Swagger）規範定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。

　　爲何要使用 Swagger

　　當下不少公司都採起先後端分離的開發模式，前端和後端的工做由不一樣的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提升咱們的工做效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信你們也都知道這種方式很難保證文檔的及時性，這種文檔長此以往也就會失去其參考意義，反而還會加大咱們的溝通成本。而 Swagger 給咱們提供了一個全新的維護 API 文檔的方式，下面咱們就來了解一下它的優勢：html

代碼變，文檔變。只須要少許的註解，Swagger 就能夠根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。
跨語言性，支持 40 多種語言。
Swagger UI 呈現出來的是一份可交互式的 API 文檔，咱們能夠直接在文檔頁面嘗試 API 的調用，省去了準備複雜的調用參數的過程。
還能夠將文檔規範導入相關的工具（例如 SoapUI）, 這些工具將會爲咱們自動地建立自動化測試。

Swagger 使用

　　準備項目

　　一、準備一個Spring的Maven Web項目（test-swagger），參考：，pom.xml文件以下：前端

pom.xml

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mvc="http://www.springframework.org/schema/mvc"
 3     xmlns:context="http://www.springframework.org/schema/context" xmlns:tx="http://www.springframework.org/schema/tx" xmlns:util="http://www.springframework.org/schema/util"
 4     xmlns:aop="http://www.springframework.org/schema/aop"
 5     xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd
 6         http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd    
 7         http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsd
 8         http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-4.0.xsd
 9         http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx.xsd
10         http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-4.0.xsd">
11 
12     
13     <!-- 註解註冊 -->
14     <context:annotation-config />
15     
16     <context:component-scan base-package="com.test" />
17     
18 </beans>

spring-context.xml

 1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 2 <beans xmlns="http://www.springframework.org/schema/beans"
 3     xmlns:context="http://www.springframework.org/schema/context"
 4     xmlns:aop="http://www.springframework.org/schema/aop" xmlns:mvc="http://www.springframework.org/schema/mvc"
 5     xmlns:p="http://www.springframework.org/schema/p" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 6     xsi:schemaLocation="http://www.springframework.org/schema/beans  http://www.springframework.org/schema/beans/spring-beans-4.0.xsd 
 7         http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsd
 8         http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd
 9         http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-4.0.xsd">
10 
11     <!-- 自動掃描的包名 -->
12     <context:component-scan base-package="com.test.swagger" />
13 
14     <!-- 默認的註解映射的支持 -->
15     <mvc:annotation-driven>
16         <mvc:message-converters>
17             <bean class="org.springframework.http.converter.StringHttpMessageConverter" />
18             <bean
19                 class="org.springframework.http.converter.ResourceHttpMessageConverter" />
20         </mvc:message-converters>
21     </mvc:annotation-driven>
22 
23 
24 
25     <!-- 視圖解釋類,定義跳轉的文件的先後綴 -->
26     <!-- <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver"> 
27         <property name="viewClass" value="org.springframework.web.servlet.view.JstlView" 
28         /> <property name="prefix" value="/views/" /> <property name="suffix" value=".jsp" 
29         /> <property name="requestContextAttribute" value="rc" /> </bean> -->
30     <bean id="viewResolver"
31         class="org.springframework.web.servlet.view.InternalResourceViewResolver">
32         <property name="viewClass"
33             value="org.springframework.web.servlet.view.JstlView" />
34         <property name="prefix" value="/view/" />
35         <property name="suffix" value=".jsp" />
36     </bean>
37 
38 
39     <!-- 對靜態資源文件的訪問 方案一 （二選一） -->
40     <mvc:default-servlet-handler />
41 
42     <!-- 對靜態資源文件的訪問 方案二 （二選一） -->
43     <!-- <mvc:resources mapping="/images/**" location="/images/" cache-period="31556926"/> 
44         <mvc:resources mapping="/js/**" location="/js/" cache-period="31556926"/> 
45         <mvc:resources mapping="/css/**" location="/css/" cache-period="31556926"/> -->
46 </beans>

spring-mvc.xml　　

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3     xmlns="http://java.sun.com/xml/ns/javaee"
 4     xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
 5     id="WebApp_ID" version="3.0">
 6     <display-name>test-swagger</display-name>
 7 
 8     <!-- 指定Spring Bean的配置文件所在目錄。默認配置在WEB-INF目錄下 -->
 9     <context-param>
10         <param-name>contextConfigLocation</param-name>
11         <param-value>classpath:spring-context.xml</param-value>
12     </context-param>
13     
14 
15     <!-- Spring配置 -->
16     <listener>
17         <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
18     </listener>
19 
20     <!-- Spring MVC配置 -->
21     <servlet>
22         <servlet-name>spring</servlet-name>
23         <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
24         <!-- 能夠自定義servlet.xml配置文件的位置和名稱，默認爲WEB-INF目錄下，名稱爲[<servlet-name>]-servlet.xml，如spring-servlet.xml -->
25         <init-param>
26             <param-name>contextConfigLocation</param-name>
27             <param-value>classpath:spring-mvc.xml</param-value>
28         </init-param>
29         <load-on-startup>1</load-on-startup>
30     </servlet>
31 
32     <servlet-mapping>
33         <servlet-name>spring</servlet-name>
34         <url-pattern>/</url-pattern>
35     </servlet-mapping>
36 
37 
38     <!-- 中文過濾器 -->
39     <filter>
40         <filter-name>CharacterEncodingFilter</filter-name>
41         <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
42         <init-param>
43             <param-name>encoding</param-name>
44             <param-value>UTF-8</param-value>
45         </init-param>
46         <init-param>
47             <param-name>forceEncoding</param-name>
48             <param-value>true</param-value>
49         </init-param>
50     </filter>
51     <filter-mapping>
52         <filter-name>CharacterEncodingFilter</filter-name>
53         <url-pattern>/*</url-pattern>
54     </filter-mapping>
55 
56     <welcome-file-list>
57         <welcome-file>index.jsp</welcome-file>
58     </welcome-file-list>
59 </web-app>

web.xml

　　二、編寫接口，UserController 提供用戶的增、刪、改、查四個接口java

 1 package com.test.swagger.controller;
 2 
 3 import org.springframework.web.bind.annotation.DeleteMapping;
 4 import org.springframework.web.bind.annotation.GetMapping;
 5 import org.springframework.web.bind.annotation.PathVariable;
 6 import org.springframework.web.bind.annotation.PostMapping;
 7 import org.springframework.web.bind.annotation.PutMapping;
 8 import org.springframework.web.bind.annotation.RequestBody;
 9 import org.springframework.web.bind.annotation.RequestMapping;
10 import org.springframework.web.bind.annotation.RestController;
11 
12 import com.test.swagger.model.User;
13 
14 import io.swagger.annotations.Api;
15 import io.swagger.annotations.ApiOperation;
16 
17 @Api(tags = "用戶相關接口") 
18 @RestController
19 @RequestMapping("/user")
20 public class UserController {
21 
22     @ApiOperation("新增用戶接口")
23     @PostMapping("/add")
24     public boolean addUser(@RequestBody User user) {
25         return false;
26     }
27 
28     @GetMapping("/find/{id}")
29     public User findById(@PathVariable("id") int id) {
30         return new User();
31     }
32 
33     @PutMapping("/update")
34     public boolean update(@RequestBody User user) {
35         return true;
36     }
37 
38     @DeleteMapping("/delete/{id}")
39     public boolean delete(@PathVariable("id") int id) {
40         return true;
41     }
42 }

UserController.java

 1 package com.test.swagger.model;
 2 
 3 import io.swagger.annotations.ApiModel;
 4 import io.swagger.annotations.ApiModelProperty;
 5 
 6 @ApiModel("用戶實體")
 7 public class User {
 8 
 9     @ApiModelProperty("用戶 ID")
10     private Integer id;
11 
12     @ApiModelProperty("用戶 名稱")
13     private String name;
14 
15     public Integer getId() {
16         return id;
17     }
18 
19     public void setId(Integer id) {
20         this.id = id;
21     }
22 
23     public String getName() {
24         return name;
25     }
26 
27     public void setName(String name) {
28         this.name = name;
29     }
30     
31     
32 }

User.java

　　集成 Swagger2

　　三、添加Swagger2依賴，以下：web

 1 <dependency>
 2     <groupId>io.springfox</groupId>
 3     <artifactId>springfox-swagger2</artifactId>
 4     <version>2.9.2</version>
 5 </dependency>

　　四、Swagger2配置，Springfox 提供了一個 Docket 對象，讓咱們能夠靈活的配置 Swagger 的各項屬性。下面咱們新建一個SwaggerConfig.java 類，在SpringMvc掃描該類，就是將該類注入SpringMvc中，並增長以下內容:spring

 1 package com.test.swagger.conf;
 2 
 3 import org.springframework.context.annotation.Bean;
 4 import org.springframework.context.annotation.Configuration;
 5 
 6 import springfox.documentation.builders.PathSelectors;
 7 import springfox.documentation.builders.RequestHandlerSelectors;
 8 import springfox.documentation.spi.DocumentationType;
 9 import springfox.documentation.spring.web.plugins.Docket;
10 import springfox.documentation.swagger2.annotations.EnableSwagger2;
11 
12 @Configuration
13 @EnableSwagger2 // 做用是啓用Swagger2相關功能。
14 public class SwaggerConfig {
15 
16     @Bean
17     public Docket api() {
18         return new Docket(DocumentationType.SWAGGER_2)
19                 .select()    // 選擇那些路徑和api會生成document
20                 .apis(RequestHandlerSelectors.any()) // 對全部api進行監控
21                 .paths(PathSelectors.any())     // 對全部路徑進行監控
22                 .build();
23     }
24 }

　　五、驗證集成了 Swagger2是否成功，發佈項目，瀏覽器使用地址（http://ip:端口/項目名/v2/api-docs）：http://localhost:8080/test-swagger/v2/api-docs，進行訪問，發現返回的結果是一段 JSON 串，可讀性很是差apache

　　集成 Swagger UI

　　Swagger2 爲咱們提供了可視化的交互界面 SwaggerUI後端

　　六、添加SwaggerUI依賴api

1 <dependency>
2     <groupId>io.springfox</groupId>
3     <artifactId>springfox-swagger-ui</artifactId>
4     <version>2.9.2</version>
5 </dependency>

　　七、驗證集成了 SwaggerUI是否成功，發佈項目，瀏覽器使用地址（http://ip:端口/項目名/swagger-ui.html）：http://localhost:8080/test-swagger/swagger-ui.html瀏覽器

Swagger 註解配置

　　文檔相關描述配置

　　一、經過在控制器類上增長@Api 註解，能夠給控制器增長描述和標籤信息。

　　　　給 Controller 添加描述信息

1 @Api(tags = "用戶相關接口", description = "提供用戶相關的 Rest API")
2 public class UserController

　　二、經過在接口方法上增長 @ApiOperation 註解來展開對接口的描述，固然這個註解還能夠指定不少內容

　　　　給接口添加描述信息

1 @ApiOperation("新增用戶接口")
2 @PostMapping("/add")
3 public boolean addUser(@RequestBody User user) {
4     return false;
5 }

　　三、實體描述，咱們能夠經過 @ApiModel 和 @ApiModelProperty 註解來對咱們 API 中所涉及到的對象作描述。　　

　　　　給實體類添加描述信息

1 @ApiModel("用戶實體")
2 public class User {
3     @ApiModelProperty("用戶 id")
4 　　private int id;
5 }

　　四、文檔信息配置，Swagger 還支持設置一些文檔的版本號、聯繫人郵箱、網站、版權、開源協議等等信息，但與上面幾條不一樣的是這些信息不是經過註解配置，而是經過建立一個 ApiInfo 對象，而且使用 Docket.appInfo() 方法來設置，咱們在 SwaggerConfig.java 類中新增以下內容便可　　

　　　　配置文檔信息

 1 @Bean
 2 public Docket api() {
 3     return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
 4             .paths(PathSelectors.any()).build().apiInfo(apiInfo());
 5 }
 6 
 7 private ApiInfo apiInfo() {
 8     return new ApiInfo("Spring Web 項目集成 Swagger 實例文檔", "歡迎你們訪問。", "API V1.0",
 9             "Terms of service", new Contact("OpenApi", "http://127.0.0.1", "123456@163.com"), "Apache",
10             "http://www.apache.org/", Collections.emptyList());
11 }

　　　　經過以上配置，查看UI，以下：

　　接口過濾

　　有些時候咱們並非但願全部的 Rest API 都呈如今文檔上，這種狀況下 Swagger2 提供給咱們了兩種方式配置，一種是基於 @ApiIgnore 註解，另外一種是在 Docket 上增長篩選。

　　一、@ApiIgnore 註解。若是想在文檔中屏蔽掉刪除用戶的接口（user/delete），那麼只須要在刪除用戶的方法上加上 @ApiIgnore 便可。

1 @ApiIgnore
2 public boolean delete(@PathVariable("id") int id)

　　二、在 Docket 上增長篩選。Docket 類提供了 apis() 和 paths()兩個方法來幫助咱們在不一樣級別上過濾接口：

apis()：這種方式咱們能夠經過指定包名的方式，讓 Swagger 只去某些包下面掃描。
paths()：這種方式能夠經過篩選 API 的 url 來進行過濾。

1 .apis(RequestHandlerSelectors.basePackage("com.test.swagger.controller"))
2 .paths(Predicates.or(PathSelectors.ant("/user/add"),
3         PathSelectors.ant("/user/find/*")))

　　自定義響應消息

　　Swagger 容許咱們經過 Docket 的 globalResponseMessage() 方法全局覆蓋 HTTP 方法的響應消息，可是首先咱們得經過 Docket 的 useDefaultResponseMessages 方法告訴 Swagger 不使用默認的 HTTP 響應消息，假設咱們如今須要覆蓋全部 GET 方法的 500 和 403 錯誤的響應消息，咱們只須要在 SwaggerConfig.java 類中的 Docket Bean 下添加以下內容：

 1 @Bean
 2 public Docket api() {
 3     List<ResponseMessage> responseMessageList = new ArrayList<>();
 4     responseMessageList.add( new ResponseMessageBuilder().code(500).message("服務器發生異常").responseModel(new ModelRef("Error")).build());
 5     responseMessageList.add( new ResponseMessageBuilder().code(403).message("資源不可用").build());
 6     
 7     return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any())
 8             .paths(PathSelectors.any()).build().apiInfo(apiInfo()).useDefaultResponseMessages(false)
 9             .globalResponseMessage(RequestMethod.GET,responseMessageList);
10 }