Swagger 是什么？

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

Springfox 的前身是 swagger-springmvc，是一个开源的 API doc 框架，可以将我们的 Controller 的方法以文档的形式展现，基于 Swagger。

官网：http://swagger.io/

开源地址：http://springfox.github.io/springfox/

Swagger使用

第一步：导入依赖

<!-- Swagger -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

第二步：开启 @EnableSwagger2注解

@SpringBootApplication
@RestController
@EnableSwagger2
public class DemoApplication {

第三步：访问 http://localhost:8080/swagger-ui.html

如上拦截了所有controller的API, 如何拦截固定的package，url 的API

第四步：定制url的API

可以一次性拦截所有的接口，也可以分组拦截

@Configuration
public class Swagger2Configuration {
    /*@Bean
	public Docket accessToken() {
		return new Docket(DocumentationType.SWAGGER_2).groupName("订单")// 定义组
				.select() // 选择那些路径和 api 会生成 document
				.apis(RequestHandlerSelectors.basePackage("com.zto.springboot.controller")) // 拦截的包路径
				.paths(PathSelectors.regex("/web/.*"))// 拦截的接口路径
				.build() // 创建
				.apiInfo(apiInfo()); // 配置说明
	}*/
	
	@Bean
	public Docket accessToken2() {
		return new Docket(DocumentationType.SWAGGER_2).groupName("所有接口")// 定义组
				.select() // 选择那些路径和 api 会生成 document
				.apis(RequestHandlerSelectors.basePackage("com.zto.security.web.controller")) // 拦截的包路径
				//.paths(PathSelectors.regex("/user/.*"))// 拦截的接口路径
				.paths(PathSelectors.any())  //拦截所有接口
				.build() // 创建
				.apiInfo(apiInfo()); // 配置说明
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("xxx项目接口文档")// 标题
				.description("xxx项目描述xxx项目描述xxx项目描述xxx项目描述")// 描述
				.contact(new Contact("xxx", "http://www.baidu.com","[email protected]"))// 联系
				//.termsOfServiceUrl("http://www.roncoo.com")  //服务条款的URL
				// .license("Apache License Version 2.0")// 开源协议
				// .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")//地址
				.version("1.0")// 版本
				.build();
	}

}

第五步：控制层注解使用说明

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数

@ApiOperation

@ApiOperation(value = "新增用户服务", notes = "新增用户")
@PostMapping
public User create(@Valid @RequestBody User user, BindingResult errors) {
    return user;
}

@ApiModelProperty

public class UserQueryCondition {
	
	private String username;

	@ApiModelProperty(value = "用户年龄起始值")
	private int age;

	@ApiModelProperty(value = "用户年龄终止值")
	private int ageTo;
	
	private String xxx;
}

@ApiParam

@ApiOperation(value = "用户删除服务", notes = "删除用户")
@DeleteMapping("/{id:\\d+}")
public void delete(@ApiParam("用户id") @PathVariable String id) {
   System.out.println(id);
}

最终效果

使用Swagger自动生成文档

Swagger 是什么？

Swagger使用

猜你喜欢