SpringBoot整合Swagger2

一、新增Swagger2 pom依賴檔案

1、此處為根目錄下pom依賴

1. <properties>  
2.   <swagger.version>2.4.0</swagger.version>  
3. </properties>  

1. <dependencyManagement>  
2.   <dependencies>  
3.     <dependency>                 
4.       <groupId>io.springfox</groupId>  
5.       <artifactId>springfox-swagger-ui</artifactId>                 
6.       <version>${swagger.version}</version>  
7.     </dependency>  
8.     <dependency>                 
9.       <groupId>io.springfox</groupId>  
10.       <artifactId>springfox-swagger2</artifactId>                  
11.       <version>${swagger.version}</version>  
12.     </dependency>  
13.     <!-- Swagger結束 -->  
14.   </dependencies>  
15. </dependencyManagement>  

2、當前工程下依賴

1. <!-- Swagger開始 -->  
2.  <dependency>            
3.    <groupId>io.springfox</groupId>  
4.    <artifactId>springfox-swagger-ui</artifactId>  
5.  </dependency>  
6.  <dependency>             
7.    <groupId>io.springfox</groupId>  
8.    <artifactId>springfox-swagger2</artifactId>  
9.  </dependency>  
10. <!-- Swagger結束 -->  

二、新建Swagger2配置類

下面為示例：

1. package com.fanxf;  
2. import org.springframework.context.annotation.Bean;  
3. import org.springframework.context.annotation.Configuration;  
4. import springfox.documentation.builders.ApiInfoBuilder;  
5. import springfox.documentation.builders.PathSelectors;  
6. import springfox.documentation.builders.RequestHandlerSelectors;  
7. import springfox.documentation.service.ApiInfo;  
8. import springfox.documentation.service.Contact;  
9. import springfox.documentation.spi.DocumentationType;  
10. import springfox.documentation.spring.web.plugins.Docket;  
11. import springfox.documentation.swagger2.annotations.EnableSwagger2;  
12. /** 
13.  * @author fanxf 
14.  * @date 2018/2/28 10:10 
15.  */
16. @EnableSwagger2
17. @Configuration
18. publicclass Swagger {  
19.     @Bean
20.     public Docket createRestApi() {  
21.         returnnew Docket(DocumentationType.SWAGGER_2)  
22.                 .apiInfo(apiInfo())  
23.                 .select()  
24.                 .apis(RequestHandlerSelectors.basePackage("com.fanxf.service.demo.controller")) //當前包路徑
25.                 .paths(PathSelectors.any())  
26.                 .build();  
27.     }  
28.     //構建 api文件的詳細資訊函式
29.     private ApiInfo apiInfo() {  
30.         returnnew ApiInfoBuilder()  
31.                 .title("api文件") //頁面標題
32.                 .contact(new Contact("fanxf","www.fanxf.com","[email protected]")) //建立人
33.                 .version("1.0") //版本號
34.                 .description("api文件") //描述
35.                 .build();  
36.     }  
37. }  

講解：1、@Configuration註解，讓Spring來載入該類配置，

          2、@EnableSwagger2註解來啟用Swagger2。

          3、通過buildDocket函式建立Docket的Bean之後，apiInfo()用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）。      

          4、select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現，本例採用指定掃描的包路徑

                來定義，Swagger會掃描該包下所有Controller定義的API，併產生文件內容（除了被@ApiIgnore註解的API）。

三、controller編寫

程式碼如下：

1. package com.fanxf.service.demo.controller;  
2. import com.fanxf.ColorRespDto;  
3. import com.fanxf.domain.Style;  
4. import com.fanxf.service.StyleService;  
5. import io.swagger.annotations.ApiImplicitParam;  
6. import io.swagger.annotations.ApiOperation;  
7. import org.apache.commons.lang.StringUtils;  
8. import org.springframework.beans.factory.annotation.Autowired;  
9. import org.springframework.web.bind.annotation.GetMapping;  
10. import org.springframework.web.bind.annotation.PathVariable;  
11. import org.springframework.web.bind.annotation.RequestMapping;  
12. import org.springframework.web.bind.annotation.RestController;  
13. import java.util.ArrayList;  
14. import java.util.List;  
15. /** 
16.  * @author fanxf 
17.  * @date 2018/2/6 16:13 
18.  */
19. @RestController
20. @RequestMapping("/demo")  
21. publicclass ColorController {  
22.     @Autowired
23.     private StyleService styleService;  
24.     @ApiOperation(value = "查詢車輛顏色", notes = "根據車型id查詢所有顏色")  
25.     @ApiImplicitParam(name = "id", value = "車型id", dataType = "String", paramType = "path")  
26.     @GetMapping("/color/{id}")  
27.     public ColorRespDto getList(@PathVariable String id) {  
28.         Style style = styleService.selectById(id);  
29.     if (null == style) {  
30.         returnnull;  
31.     }  
32.         List<String> list = new ArrayList<String>();  
33.         String[] str = style.getColor().split(".");  
34.         for (String color : str) {  
35.             list.add(color);  
36.         }  
37.         ColorRespDto dto = new ColorRespDto();  
38.         dto.setColor(list);  
39.         return dto;  
40.     }  
41. }  

講解：1、@ApiOperation：用在方法上，說明方法的作用，標註在具體請求上，value和notes的作用差不多，都是對請求進行

                 說明

           2、@ApiImplicitParams：用在方法上包含一組引數說明

3、@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面

　　            paramType：引數放在哪個地方

　　            header 請求引數的獲取：@RequestHeader

　　            query 請求引數的獲取：@RequestParam

　　            path（用於restful介面） 請求引數的獲取：@PathVariable

　　            body（不常用）

　　            form（不常用）

　　            name：引數名

　　            dataType：引數型別

　　            required：引數是否必須傳

　　            value：引數的意思

　　            defaultValue：引數的預設值

完成controller後啟動springboot

如圖：

可以看到其中的controller

點選然後進行訪問：