Springboot集成swagger2生成接口文檔

時間 2019-11-24

標籤 springboot 集成 swagger2 swagger 生成接口文檔欄目 Spring 简体版

原文原文鏈接

【轉載請註明】：html

原文出處：http://www.javashuo.com/article/p-nkrroydz-e.html 做者：jstarseven 碼字挺辛苦的..... 前端

1、Swagger介紹

Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化RESTful風格的web服務。目標是使客戶端和文件系統做爲服務器以一樣的速度來更新文件的方法，參數和模型緊密集成到服務器。這個解釋簡單點來說就是說，swagger是一款能夠根據restful風格生成的接口開發文檔，而且支持作測試的一款中間軟件。java

2、使用swagger優點

一、對於後端開發人員來講

不用再手寫Wiki接口拼大量參數，避免手寫錯誤

對代碼侵入性低，採用全註解的方式，開發簡單

方法參數名修改、新增、減小參數均可以直接生效，不用手動維護

缺點：增長了開發成本，寫接口還得再寫一套參數配置

二、對前端開發來講

後端只須要定義好接口，會自動生成文檔，接口功能、參數一目瞭然

聯調方便，若是出了問題，直接測試接口，實時檢查參數和返回值，就能夠快速定位是前端仍是後端的問題

三、對於測試來講

但對於測試沒有前端界面UI的功能，能夠直接用它來測試接口

操做簡單，不用瞭解具體代碼就能夠操做

3、springboot集成swagger使用

一、新建maven項目（結構以下：）

二、配置pom.xml文件

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 3          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 4     <modelVersion>4.0.0</modelVersion>
 5     <parent>
 6         <groupId>org.springframework.boot</groupId>
 7         <artifactId>spring-boot-starter-parent</artifactId>
 8         <version>2.1.3.RELEASE</version>
 9         <relativePath/>
10     </parent>
11     <groupId>com.dds.sbswagger</groupId>
12     <artifactId>sb-swagger</artifactId>
13     <version>0.0.1-SNAPSHOT</version>
14     <name>sb-swagger</name>
15     <description>Demo project for Spring Boot</description>
16 
17     <properties>
18         <java.version>1.8</java.version>
19     </properties>
20     <dependencies>
21         <dependency>
22             <groupId>org.springframework.boot</groupId>
23             <artifactId>spring-boot-starter-web</artifactId>
24         </dependency>
25         <dependency>
26             <groupId>org.springframework.boot</groupId>
27             <artifactId>spring-boot-starter-test</artifactId>
28             <scope>test</scope>
29         </dependency>
30         <dependency>
31             <groupId>io.springfox</groupId>
32             <artifactId>springfox-swagger2</artifactId>
33             <version>2.9.2</version>
34         </dependency>
35         <dependency>
36             <groupId>io.springfox</groupId>
37             <artifactId>springfox-swagger-ui</artifactId>
38             <version>2.9.2</version>
39         </dependency>
40         <dependency>
41             <groupId>org.projectlombok</groupId>
42             <artifactId>lombok</artifactId>
43             <version>1.18.6</version>
44         </dependency>
45     </dependencies>
46     <build>
47         <plugins>
48             <plugin>
49                 <groupId>org.springframework.boot</groupId>
50                 <artifactId>spring-boot-maven-plugin</artifactId>
51             </plugin>
52         </plugins>
53     </build>
54 </project>

三、程序啓動類

 1 package com.dds.sbswagger;
 2 
 3 import lombok.extern.slf4j.Slf4j;
 4 import org.springframework.boot.SpringApplication;
 5 import org.springframework.boot.autoconfigure.SpringBootApplication;
 6 
 7 /**
 8  * @author dds
 9  */
10 @SpringBootApplication
11 @Slf4j
12 public class SbSwaggerApplication {
13 
14     public static void main(String[] args) {
15         SpringApplication.run(SbSwaggerApplication.class, args);
16         log.info("\n----------------------------------------------------------\n\t" +
17                 "Application demo is running! Access URLs:\n\t" +
18                 "swagger-ui: \thttp://127.0.0.1:8080/swagger-ui.html\n\t" +
19                 "----------------------------------------------------------");
20     }
21 
22 }

四、SwaggerConfig配置類web

 1 package com.dds.sbswagger.config;
 2 
 3 import io.swagger.annotations.ApiOperation;
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.PathSelectors;
 7 import springfox.documentation.builders.RequestHandlerSelectors;
 8 import springfox.documentation.service.ApiInfo;
 9 import springfox.documentation.service.Contact;
10 import springfox.documentation.spi.DocumentationType;
11 import springfox.documentation.spring.web.plugins.Docket;
12 import springfox.documentation.swagger2.annotations.EnableSwagger2;
13 
14 import java.util.Collections;
15 
16 /**
17  * @author DDS
18  * @date 2019/9/10 13:55
19  */
20 @Configuration
21 @EnableSwagger2
22 public class SwaggerConfig {
23     @Bean
24     public Docket api() {
25         return new Docket(DocumentationType.SWAGGER_2)
26                 .select()
27                 .apis(RequestHandlerSelectors.basePackage("com.dds.sbswagger.controller"))
28                 //加了ApiOperation註解的類，才生成接口文檔
29                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
30                 .paths(PathSelectors.any())
31                 .build()
32                 .apiInfo(apiInfo());
33     }
34 
35     private ApiInfo apiInfo() {
36         return new ApiInfo(
37                 "Spring Boot項目集成Swagger實例文檔",
38                 "個人微信公衆號：大道七哥，歡迎你們關注。",
39                 "API V1.0",
40                 "Terms of service",
41                 new Contact("大道七哥", "https://www.cnblogs.com/jstarseven/", "jstarseven@163.com"),
42                 "Apache", "http://www.apache.org/", Collections.emptyList());
43     }
44 }

五、實體類modelspring

 1 package com.dds.sbswagger.model;
 2 
 3 import io.swagger.annotations.ApiModel;
 4 import io.swagger.annotations.ApiModelProperty;
 5 import lombok.Data;
 6 
 7 /**
 8  * @author DDS
 9  * @date 2019/9/10 13:55
10  */
11 @ApiModel("用戶實體")
12 @Data
13 public class User {
14 
15     /**
16      * 用戶Id
17      */
18     @ApiModelProperty("用戶id")
19     private int id;
20 
21     /**
22      * 用戶名
23      */
24     @ApiModelProperty(value = "用戶姓名", example = "zhangdan", required = true)
25     private String name;
26 
27     /**
28      * 用戶地址
29      */
30     @ApiModelProperty(value = "用戶地址", example = "北京市海淀區", required = true)
31     private String address;
32 
33     /**
34      * 用戶手機號
35      */
36     @ApiModelProperty(value = "用戶手機號", example = "15689652367", required = true)
37     private String phone;
38 
39     /**
40      * 用戶年齡
41      */
42     @ApiModelProperty(value = "用戶年齡", example = "24", required = true)
43     private Integer age;
44 
45 }

六、接口開發

 1 package com.dds.sbswagger.controller;
 2 
 3 import com.dds.sbswagger.model.User;
 4 import io.swagger.annotations.*;
 5 import org.springframework.web.bind.annotation.*;
 6 
 7 /**
 8  * @author DDS
 9  * @date 2019/9/10 13:55
10  */
11 @RestController
12 @RequestMapping("/user")
13 @Api(tags = "用戶相關接口", description = "提供用戶相關的Rest API")
14 public class UserController {
15 
16     @PostMapping("/add")
17     @ApiOperation(value = "新增用戶接口", notes = "手機號、密碼都是必輸項，年齡隨邊填，但必須是數字")
18     @ApiImplicitParams({
19             @ApiImplicitParam(name = "name", value = "用戶名稱", required = true, paramType = "form"),
20             @ApiImplicitParam(name = "address", value = "用戶地址", required = true, paramType = "form"),
21             @ApiImplicitParam(name = "phone", value = "用戶手機號", required = true, paramType = "form"),
22             @ApiImplicitParam(name = "age", value = "用戶年齡", required = true, paramType = "form", dataType = "Integer")
23     })
24     public boolean addUser(@RequestBody User user) {
25         return false;
26     }
27 
28     @ApiOperation("經過id查找用戶接口")
29     @GetMapping("/find/{id}")
30     public User findById(@PathVariable("id") int id) {
31         return new User();
32     }
33 
34     @ApiOperation("更新用戶信息接口")
35     @PutMapping("/update")
36     @ApiResponses({
37             @ApiResponse(code = 400, message = "請求參數沒填好"),
38             @ApiResponse(code = 404, message = "請求路徑沒有或頁面跳轉路徑不對"),
39             @ApiResponse(code = 405, message = "未知錯誤")
40     })
41     public boolean update(@RequestBody User user) {
42         return true;
43     }
44 
45     @ApiOperation("刪除用戶接口")
46     @DeleteMapping("/delete/{id}")
47     public boolean delete(@PathVariable("id") int id) {
48         return true;
49     }
50 }