本文介绍 Spring Boot 2 集成 SpringFox 生成 Swagger 2.0 API 文档的方法。
目录
-
Swagger2简介 -
SpringFox简介 - 开发环境
- 基础示例
- 配置详解
-
@ApiOperation详解 -
@ApiImplicitParam详解 -
@ApiImplicitParams详解 -
@ApiParam详解 - 总结
Swagger2 简介
Swagger2 是一款功能强大的 API 构建工具。
SpringFox 简介
SpringFox 用于在 Spring 应用中自动化构建 API 文档。
开发环境
- Oracle JDK 1.8.0_201
- Apache Maven 3.6.0
- IntelliJ IDEA (Version 2018.3.3)
基础示例
-
创建 Spring Boot 工程，参考：IntelliJ IDEA 创建 Spring Boot 工程。
-
生成的
pom文件如下，注意需要添加springfox-swagger2和springfox-swagger-ui依赖。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.4.RELEASE</version>
<relativePath/>
</parent>
<groupId>tutorial.spring.boot</groupId>
<artifactId>spring-boot-swagger2</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>spring-boot-swagger2</name>
<description>Spring Boot Swagger2</description>
<properties>
<java.version>1.8</java.version>
<swagger.version>2.9.2</swagger.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
- 添加
Swagger2配置类。
package tutorial.spring.boot.swagger2.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* 启用 Springfox swagger 2 的配置类
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 注入 springfox.documentation.spring.web.plugins.Docket 对象
*/
@Bean
public Docket petApi() {
// Docket 是 Springfox 主要的 API 配置机制，初始化 Swagger 2.0 规范
return new Docket(DocumentationType.SWAGGER_2)
/*
* select() 返回 springfox.documentation.spring.web.plugins.ApiSelectorBuilder 实例，
* 对 Swagger 暴露的端点执行细粒度控制。
*/
.select()
/*
* apis(RequestHandlerSelectors.any()) 允许使用谓词选择 RequestHandler，
* 此处示例使用任意谓词（默认），
* 开箱即用的谓词有：any, none, withClassAnnotation, withMethodAnnotation, basePackage。
*/
.apis(RequestHandlerSelectors.any())
/*
* paths(PathSelectors.any()) 允许使用谓词选择 Path，
* 此处示例使用任意谓词（默认），
* 开箱即用的谓词有：regex, ant, any, none
*/
.paths(PathSelectors.any())
// 配制完 api 和 path 后需要构建选择器
.build();
}
}
- 添加带 API 文档的
controller类。
package tutorial.spring.boot.swagger2.controller;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicLong;
@RestController
@RequestMapping("/planets")
public class PlanetController {
private final AtomicLong idCounter = new AtomicLong();
private Map<Long, String> planets;
/**
* 初始化行星
*/
@PostConstruct
public void init() {
planets = new HashMap<>(16);
long id = idCounter.incrementAndGet();
planets.put(id, "Mercury");
id = idCounter.incrementAndGet();
planets.put(id, "Venus");
id = idCounter.incrementAndGet();
planets.put(id, "Earth");
id = idCounter.incrementAndGet();
planets.put(id, "Mars");
id = idCounter.incrementAndGet();
planets.put(id, "Jupiter");
id = idCounter.incrementAndGet();
planets.put(id, "Saturn");
id = idCounter.incrementAndGet();
planets.put(id, "Uranus");
id = idCounter.incrementAndGet();
planets.put(id, "Neptune");
id = idCounter.incrementAndGet();
planets.put(id, "Pluto");
}
@ApiOperation(value = "根据 ID 获取行星名称", notes = "根据 ID 获取行星名称")
@ApiImplicitParam(name = "id", value = "行星ID", required = true, dataType = "Integer", paramType = "path")
@GetMapping(value = "/{id}")
public String get(@PathVariable Long id) {
return planets.get(id);
}
@ApiOperation(value = "获取所有行星名称列表", notes = "获取所有行星名称列表")
@GetMapping("/")
public List<String> list() {
return new ArrayList<>(planets.values());
}
}
-
启动应用，打开浏览器访问
http://localhost:8080/swagger-ui.html显示所有 API 列表。 -
浏览器访问
http://localhost:8080/v2/api-docs显示所有接口的 JSON 描述文件。
配置详解
@ApiOperation 详解
io.swagger.annotations.ApiOperation 描述针对特定路径的操作，通常是 HTTP 方法。
常用属性：
-
value：类型String，必需
@ApiImplicitParam 详解
io.swagger.annotations.ApiImplicitParam 描述 API 接口中的单个参数。
@ApiImplicitParams 详解
io.swagger.annotations.ApiImplicitParam 对象集合。
@ApiParam 详解
io.swagger.annotations.ApiParam 为参数添加额外元数据，此注解只能与 JAX-RS 1.x / 2.x 注解组合使用。
网友评论