SpringBoot整合Swagger自動生成API文檔

SpringBoot整合Swagger自動生成API文檔

java_zhangwei 2018-07-27 14:38:54 1395 已收藏 3
展開
目錄

1.引入Swagger依賴（我這裏使用的2.2.2版本，儘可能別使用新版本，不穩定）

2.編寫Swagger配置

 

3.編寫Controller

4.一切準備就緒，如今打開網頁試試

5.相關的註解解釋

6.在此過程當中出現的一些問題：

Swagger是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件，相比於傳統的postman插件，其優勢在於：

先後端能夠分離開發
API文檔很是明確
測試的時候不須要輸入url連接
SpringBoot與Swagger結合很是簡單
 

1.引入Swagger依賴（我這裏使用的2.2.2版本，儘可能別使用新版本，不穩定）

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
<scope>compile</scope>
</dependency>

 

2.編寫Swagger配置

 1 package top.javazhangwei.webconfig;
 2 
 3 
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.ApiInfoBuilder;
 7 import springfox.documentation.builders.PathSelectors;
 8 import springfox.documentation.builders.RequestHandlerSelectors;
 9 import springfox.documentation.service.ApiInfo;
10 import springfox.documentation.spi.DocumentationType;
11 import springfox.documentation.spring.web.plugins.Docket;
12 import springfox.documentation.swagger2.annotations.EnableSwagger2;
13 
14 /***
15 * 指定API文檔頁的標題和描述信息等內容。
16 */
17 @Configuration
18 @EnableSwagger2
19 public class MySwagger {
20 @Bean
21 public Docket createRestApi() {
22 return new Docket(DocumentationType.SWAGGER_2)
23 .apiInfo(apiInfo())
24 .select()
25 .apis(RequestHandlerSelectors.basePackage("top.javazhangwei.controller"))//這裏是controller所處的包名
26 .paths(PathSelectors.any())
27 .build();
28 }
29 //構建api文檔的詳細信息函數
30 private ApiInfo apiInfo() {
31 return new ApiInfoBuilder()
32 //頁面標題
33 .title("spring-boot-web-crud項目")
34 //描述
35 .description("api查詢測試接口")
36 .termsOfServiceUrl("API terms of service")
37 //版本號s
38 .version("1.0")
39 .build();
40 }
41 }

View Code

 

說明：

在這裏特別注意下：apis(RequestHandlerSelectors.basePackage("com.yto.controller"))，這個是你Controller所在的包名
配置完後，打開http://127.0.0.1:8080/swagger-ui.html#/看是否能訪問不
 
3.編寫Controller

 1 package top.javazhangwei.controller;
 2 
 3 import top.javazhangwei.entities.Diary;
 4 import top.javazhangwei.mapper.DiaryMapper;
 5 import io.swagger.annotations.Api;
 6 import io.swagger.annotations.ApiOperation;
 7 import org.apache.catalina.servlet4preview.http.HttpServletRequest;
 8 import org.springframework.web.bind.annotation.RequestMapping;
 9 import org.springframework.web.bind.annotation.RestController;
10 
11 import javax.annotation.Resource;
12 import java.util.List;
13 
14 @RestController
15 @Api(description = "測試api")
16 public class MyController {
17 @Resource
18 private DiaryMapper diaryMapper;
19 //查詢文章和用戶信息
20 @ApiOperation("測試關聯查詢文章和用戶信息")
21 @RequestMapping("/testDiary")
22 public List<Diary> getAllDiaryAndUsers(HttpServletRequest request){
23 List<Diary> list =diaryMapper.getAllDiary();
24 return list;
25 }
26 }
27 @Controller
28 @Api(description = "登陸api")
29 public class LoginController {
30 @Resource
31 private UsersMapper usersMapper;
32 @ApiOperation("用戶登錄")
33 @ApiImplicitParams({@ApiImplicitParam(name = "username",value = "用戶名",required = true,dataType = "String",paramType="query"),
34 @ApiImplicitParam(name = "password",value = "密碼",required = true,dataType = "String",paramType="query")})
35 @PostMapping(value = "/user/login")
36 public String postLogin( @RequestParam("username") String username, @RequestParam("password") String password, HttpSession session, HttpServletRequest request) {
37 Users users =usersMapper.login(username,password);
38 if(users!=null){
39 session.setAttribute("user",users);
40 return "redirect:/main.html";
41 }else{
42 request.setAttribute("msg","用戶名或密碼錯誤");
43 return "login";
44 }
45 }
46 
47 //返回登陸界面
48 
49 @RequestMapping("/login")
50 @ApiOperation("返回登陸界面")
51 public String login(){
52 return "login";
53 }
54 
55 }

View Code

 

4.一切準備就緒，如今打開網頁試試
若是訪問不了頁面或者頁面的數據沒改過來，嘗試清除一下瀏覽器緩存~

 

 

 

5.相關的註解解釋

其餘註解查看官方文檔源碼： 
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel

6.在此過程當中出現的一些問題：
       1.出現這種提示：

 

 

 

    頗有多是沒在Swagger配置上添加自動配置註解：@EnableSwagger2

    或者就是沒有掃到controller，檢查檢查swagger配置上的包名是否正確

 

     2.出現failed to parse JSON/YAML response的問題

       這個緣由就是攔截器把swagger請求攔截了，因此沒有接口信息，只須要加個判斷容許swagger容許訪問便可。

String url=httpServletRequest.getRequestURI();

if(url.indexOf("swagger")!=-1||url.indexOf("api-docs")!=-1){
return true;
}
 
————————————————
原文連接：http://www.javashuo.com/article/p-kuxvaeiv-bz.html