Swagger的介绍与使用

1、描述

  Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

作用：

• 使接口文档在线自动生成。
• 功能测试。

2、使用

【1】在maven中导入swagger

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.6.1</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.6.1</version>
</dependency>

【2】创建Swagger2配置类

@Configuration
@EnableSwagger2
public class Swagger {
   @Bean
   public Docket docket(){
       return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.example.springbootjpa.jpademo.controller"))
         .paths(PathSelectors.any())
         .build();
   }
​
   public ApiInfo apiInfo(){
       return new ApiInfoBuilder()
         .title("利用swagger2构建的API文档")
         .description("用restful风格写接口")
         .termsOfServiceUrl("")
         .version("1.0")
         .build();
   }
}

相关说明：

• DocumentationType.SWAGGER_2告诉Docket bean我们正在使用Swagger规范的版本2。
• select()创建一个构建器，用于定义哪些控制器及其生成的文档中应包含哪些方法。
• apis()定义要包含的类（控制器和模型类）。这里我们包括所有这些，但您可以通过基础包，类注释等来限制它们。
• paths()允许您根据路径映射定义应包含哪个控制器的方法。我们现在包括所有这些，但您可以使用正则表达式等限制它。
• docket()方法创建Docket的Bean对象。
• apiInfo()则是创建ApiInfo的基本信息。
• 链式方法解析。

3、注解及其说明

• @Api: 用在类上，说明该类的主要作用。
• @ApiOperation：用在方法上，给API增加方法说明。
• @ApiImplicitParams : 用在方法上，包含一组参数说明。
• @ApiImplicitParam：用来注解来给方法入参增加说明。
• @ EnableSwagger2支持Swagger 2的SpringFox支持。

4、使用JSR-303注解

public class Person {     
	@NotNull     
	private int id;      
	@NotBlank     
	@Size(min = 1, max = 20)     
	private String firstName;      
	@NotBlank     
	@Pattern(regexp ="[SOME REGULAR EXPRESSION]")     
	private String lastName;      
	@Min(0)     
	@Max(100)     
	private int age;      
	//... Constructor, getters, setters, ... 
}

  SpringFox可以根据这些注释生成Swagger文档，因此您可以利用项目中已有的内容而无需手动编写所有约束！

需要配置相关信息：

a. 依赖：

<dependency>    
	<groupId>io.springfox</groupId>    
	<artifactId>springfox-bean-validators</artifactId>
	<version>2.9.2</version>    			      
</dependency>

b. 需要在swagger配置类之上导入BeanValidatorPluginsConfiguration配置文件

@Configuration 
@EnableSwagger2 
@Import(BeanValidatorPluginsConfiguration.class) 
public class SpringFoxConfig {  
 ... 
}