Swagger构建API文档详细教程

Swagger 简介

Swagger 是一款用于生成、描述、调用和可视化 RESTful 风格的 Web 服务接口文档的框架。其最大的特点莫过于可以使接口文档与代码实时同步。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

基于springBoot使用Swagger的应用流程

1、pom.xml 文件中引用相关依赖

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

2、编写 Swagger2 配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
	@Bean
	public Docket createDocket(){
	    return new Docket(DocumentationType.SWAGGER_2)
	            .apiInfo(apiInfo())
	            .groupName("渔火照月光")
	            .enable(true)
	            .select()
	            .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
	            .paths(PathSelectors.any())
	            .build();
	}

	private ApiInfo apiInfo(){
        return new ApiInfo
                (	
                	"Api Documentation",
	                "Description Api Documentation",
	                "version 1.0.0",
	                "termsOfServiceUrl",
	                 DEFAULT_CONTACT,
                  	"License Apache 2.0",
                  	"LicenseUrl http://www.apache.org/licenses/LICENSE-2.0",
                  	 new ArrayList<>()
                );
    }
}

• apiInfo()

// Docket类中 apiInfo()方法，设置 API 接口文档信息，并返回 Docket 对象。
public Docket apiInfo(ApiInfo apiInfo)	

// ApiInfo类的构造方法
public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, 
			String license, String licenseUrl, Collection<VendorExtension> vendorExtensions) 

// Contact类的构造方法，设置 author 的 name、Website、Email
public Contact(String name, String url, String email)

• groupName()

// groupName()设置分组名称
public Docket groupName(String groupName) {
        this.groupName = (String)BuilderDefaults.defaultIfAbsent(groupName, this.groupName);
        return this;
	}

• enable()

// 通过 enable 属性，在 application-{profile}.properties/yml 文件中设置相应值，控制在生产环境中不生成接口文档。
public Docket enable(boolean externallyConfiguredFlag)

• select()

public ApiSelectorBuilder select() {
        return new ApiSelectorBuilder(this);
    }

• apis()

// ApiSelectorBuilder类中 apis()方法，选择性扫描代码块 生成 API 接口文档
// apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) 扫描被 @RestController 修饰的类下的所有方法。 
// apis(RequestHandlerSelectors.any())
// apis(RequestHandlerSelectors.none())
// apis(RequestHandlerSelectors.basePackage("com.welljoint.controller"))
// apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) {
        this.requestHandlerSelector = Predicates.and(this.requestHandlerSelector, selector);
        return this;
    }

• paths()

// paths(PathSelectors.any())
// paths(PathSelectors.none())
// paths(PathSelectors.regex(String pathRegex)) 通过正则表达式来匹配请求;
// paths(PathSelectors.ant(String antPattern)) 只扫描指定的路径下的请求。
public ApiSelectorBuilder paths(Predicate<String> selector) {
        this.pathSelector = Predicates.and(this.pathSelector, selector);
        return this;
    }

• build()

public Docket build()

3、Swagger2 重要注解介绍

@Api：标记到类上

• value：在UI界面上不显示该值
• tags：类的详细描述

@ApiOperation：标记到方法上

• value：接口名称
• notes: 接口的详细描述

@ApiImplicitParams：在请求的方法上，表示一组参数说明 。
@ApiImplicitParam：在@ApiImplicitParams注解中，指定一个参数说明。

• name：参数的名称
• value：参数的描述
• required：参数是否必须传
• dataType：参数类型
• defaultValue：参数的默认值
• paramType：参数位置
• header 对应注解：@RequestHeader
• query 对应注解：@RequestParam
• path 对应注解: @PathVariable
• body 对应注解: @requestbody

 @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true),
            @ApiImplicitParam(name = "status", value = "用户状态", required = true)
    })

@ApiResponses：表示一组响应。
@ApiResponse：在@ApiResponses中，一般用于表达一个错误的响应信息。

• code：状态码
• message：返回的自定义信息
• response：抛出异常的类

@ApiModel：标记到实体类上
@ApiModelProperty：在实体类的属性上，描述属性。

4、访问文档

Swagger2文档的默认地址是/swagger-ui.html