SpringBoot——Swagger2 接口规范

一、添加 Swagger2 的 maven依赖

打开项目中的 pom.xml文件，添加以下两个 swagger依赖。springfox-swagger2 、springfox-swagger-ui。

 1 <dependency>

 2        <groupId>io.springfox</groupId>

 3        <artifactId>springfox-swagger2</artifactId>

 4        <version>2.6.1</version>

 5 </dependency>

 6

 7 <dependency>

 8        <groupId>io.springfox</groupId>

 9        <artifactId>springfox-swagger-ui</artifactId>

10        <version>2.6.1</version>

11 </dependency>

实际上，Swagger的 API有两种类型，并在不同的工件中维护。今天我们将使用 springfox，因为这个版本可以很好地适应任何基于 spring的配置。我们还可以很容易地尝试其他配置，这应该提供相同的功能——配置中没有任何变化。

二、添加 Swagger2配置

使用 Java config的方式添加配置。为了帮助你理解这个配置，我在代码中写了相关的注释：

 1 import org.springframework.context.annotation.Bean;

 2 import org.springframework.context.annotation.Configuration;

 3 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;

 4 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

 5 import com.google.common.base.Predicates;

 6 import springfox.documentation.builders.RequestHandlerSelectors;

 7 import springfox.documentation.spi.DocumentationType;

 8 import springfox.documentation.spring.web.plugins.Docket;

 9 import springfox.documentation.swagger2.annotations.EnableSwagger2;

10

11 @Configuration

12 @EnableSwagger2

13 public class Swagger2UiConfiguration extends WebMvcConfigurerAdapter

14 {

15     @Bean

16     public Docket api() {

17         // @formatter:off

18         //将控制器注册到 swagger

19         //还配置了Swagger 容器

20         return new Docket(DocumentationType.SWAGGER_2).select()

21                  .apiInfo(apiInfo())

22                  .select()

23                  .apis(RequestHandlerSelectors.any())

24                  //扫描 controller所有包

25                  .apis(Predicates.not(RequestHandlerSelectors.basePackage("org.springframework.boot")))

26                  .paths(PathSelectors.any())

27                  .paths(PathSelectors.ant("/swagger2-demo"))

28                  .build();

29         // @formatter:on

30     }

31

32     @Override

33     public void addResourceHandlers(ResourceHandlerRegistry registry)

34     {

35         //为可视化文档启用swagger ui部件

36         registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");

37         registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

38     }

39 }

通过 api()方法返回 Docket，调用以下方法：
【1】apiInfo()方法中可以添加 api文档的基本信息（具体类型查看文档）；
【2】select()方法返回 ApiSelectorBuilder实例，用于过滤哪些 api需要显示；
【3】apis()方法中填写项目中 Controller类存放的路径；
最后 build()建立 Docket。

三、验证 Swagger2的 JSON格式文档

在application.yml中配置服务名为：swagger2-demo

server.contextPath=/swagger2-demo

maven构建并启动服务器。打开链接 http://localhost:8080/swagger2-demo/v2/api-docs，会生成一个 JSON格式的文档。这并不是那么容易理解，实际上 Swagger已经提供该文档在其他第三方工具中使用，例如当今流行的 API管理工具，它提供了API网关、API缓存、API文档等功能。

四、验证 Swagger2 UI文档

打开链接 http://localhost:8080/swagger2-demo/swagger-ui.html 在浏览器中来查看 Swagger UI文档；

五、Swagger2 注解的使用

默认生成的 API文档很好，但是它们缺乏详细的 API级别信息。Swagger提供了一些注释，可以将这些详细信息添加到 api中。如。@Api 我们可以添加这个注解在 Controller上，去添加一个基本的 Controller说明。

1 @Api(value = "Swagger2DemoRestController", description = "REST APIs related to Student Entity!!!!")

2 @RestController

3 public class Swagger2DemoRestController {

4     //...

5 }

@ApiOperation and @ApiResponses我们添加这个注解到任何 Controller的 rest方法上来给方法添加基本的描述。例如：

 1 @ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")

 2 @ApiResponses(value = {

 3             @ApiResponse(code = 200, message = "Success|OK"),

 4             @ApiResponse(code = 401, message = "not authorized!"),

 5             @ApiResponse(code = 403, message = "forbidden!!!"),

 6             @ApiResponse(code = 404, message = "not found!!!") })

 7

 8 @RequestMapping(value = "/getStudents")

 9 public List<Student> getStudents() {

10     return students;

11 }

在这里，我们可以向方法中添加标签，来在 swagger-ui中添加一些分组。@ApiModelProperty这个注解用来在数据模型对象中的属性上添加一些描述，会在 Swagger UI中展示模型的属性。例如：

1 @ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")

2 private String name;

Controller 和 Model 类添加了swagger2注解之后，代码清单：Swagger2DemoRestController.java

 1 import java.util.ArrayList;

 2 import java.util.List;

 3 import java.util.stream.Collectors;

 4 import org.springframework.web.bind.annotation.PathVariable;

 5 import org.springframework.web.bind.annotation.RequestMapping;

 6 import org.springframework.web.bind.annotation.RestController;

 7 import com.example.springbootswagger2.model.Student;

 8 import io.swagger.annotations.Api;

 9 import io.swagger.annotations.ApiOperation;

10 import io.swagger.annotations.ApiResponse;

11 import io.swagger.annotations.ApiResponses;

12

13 @Api(value = "Swagger2DemoRestController", description = "REST Apis related to Student Entity!!!!")

14 @RestController

15 public class Swagger2DemoRestController {

16

17     List<Student> students = new ArrayList<Student>();

18     {

19         students.add(new Student("Sajal", "IV", "India"));

20         students.add(new Student("Lokesh", "V", "India"));

21         students.add(new Student("Kajal", "III", "USA"));

22         students.add(new Student("Sukesh", "VI", "USA"));

23     }

24

25     @ApiOperation(value = "Get list of Students in the System ", response = Iterable.class, tags = "getStudents")

26     @ApiResponses(value = {

27             @ApiResponse(code = 200, message = "Suceess|OK"),

28             @ApiResponse(code = 401, message = "not authorized!"),

29             @ApiResponse(code = 403, message = "forbidden!!!"),

30             @ApiResponse(code = 404, message = "not found!!!") })

31

32     @RequestMapping(value = "/getStudents")

33     public List<Student> getStudents() {

34         return students;

35     }

36

37     @ApiOperation(value = "Get specific Student in the System ", response = Student.class, tags = "getStudent")

38     @RequestMapping(value = "/getStudent/{name}")

39     public Student getStudent(@PathVariable(value = "name") String name) {

40         return students.stream().filter(x -> x.getName().equalsIgnoreCase(name)).collect(Collectors.toList()).get(0);

41     }

42

43     @ApiOperation(value = "Get specific Student By Country in the System ", response = Student.class, tags = "getStudentByCountry")

44     @RequestMapping(value = "/getStudentByCountry/{country}")

45     public List<Student> getStudentByCountry(@PathVariable(value = "country") String country) {

46         System.out.println("Searching Student in country : " + country);

47         List<Student> studentsByCountry = students.stream().filter(x -> x.getCountry().equalsIgnoreCase(country))

48                 .collect(Collectors.toList());

49         System.out.println(studentsByCountry);

50         return studentsByCountry;

51     }

52

53     // @ApiOperation(value = "Get specific Student By Class in the System ",response = Student.class,tags="getStudentByClass")

54     @RequestMapping(value = "/getStudentByClass/{cls}")

55     public List<Student> getStudentByClass(@PathVariable(value = "cls") String cls) {

56         return students.stream().filter(x -> x.getCls().equalsIgnoreCase(cls)).collect(Collectors.toList());

57     }

58 }

Student.java 实体类

 1 import io.swagger.annotations.ApiModelProperty;

 2

 3 public class Student

 4 {

 5     @ApiModelProperty(notes = "Name of the Student",name="name",required=true,value="test name")

 6     private String name;

 7

 8     @ApiModelProperty(notes = "Class of the Student",name="cls",required=true,value="test class")

 9     private String cls;

10

11     @ApiModelProperty(notes = "Country of the Student",name="country",required=true,value="test country")

12     private String country;

13

14     public Student(String name, String cls, String country) {

15         super();

16         this.name = name;

17         this.cls = cls;

18         this.country = country;

19     }

20

21     public String getName() {

22         return name;

23     }

24

25     public String getCls() {

26         return cls;

27     }

28

29     public String getCountry() {

30         return country;

31     }

32

33     @Override

34     public String toString() {

35         return "Student [name=" + name + ", cls=" + cls + ", country=" + country + "]";

36     }

37 }

六、swagger-ui 展示

现在，当我们的 REST api得到适当的注释时，让我们看看最终的输出。打开http://localhost:8080/swagger2-demo/swagger-ui。在浏览器中查看 Swagger ui 文档。