Spring Boot 集成 Swagger2 构建 RESTful API 文档

引入依赖

在 pom.xml 中添加 io.springfox:springfox-swagger2 和 io.springfox:springfox-swagger-ui 依赖

    io.springfox
    springfox-swagger2
    2.8.0


    io.springfox
    springfox-swagger-ui
    2.8.0

相关配置

创建 Swagger2Config 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("{Controler 扫描路径}"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("{标题}")
                .description("{描述}")
                .termsOfServiceUrl("{网址}")
                .version("{版本号}")
                .build();
    }
}

注意：需要在 RequestHandlerSelectors.basePackage 参数中设置 Controller 包路径，否则生成的文档扫描不到接口

在 Application 中添加 @EnableSwagger2 注解

@EnableSwagger2
@SpringBootApplication
public class ServiceAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceAdminApplication.class, args);
    }
}

使用 Swagger2

在 Controller 中的请求接口里加入以下常用 Swagger 注解

@RestController
@RequestMapping(value = "/api/v2/user")
@Api(tags = "用户管理")
public class UserController() {

    @ApiOperation(value = "分页查询用户列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "pageSize", value = "页数", required = true, dataType = "int", paramType = "path"),
            @ApiImplicitParam(name = "UserJson", value = "对象 JSON 字符串", required = false, dataTypeClass = String.class, paramType = "json")
    })
    @RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
    public BaseResult page(
        @PathVariable(required = true) int pageNum, 
        @PathVariable(required = true) int pageSize,
        @RequestParam(required = false) String UserJson
    ){
        return null;
    }
}

Swagger 注解使用说明

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

启动项目，访问 Swagger 地址：http://{ip}:{port}/swagger-ui.html

• 文章作者：彭超
• 本文首发于个人博客：https://antoniopeng.com/2019/07/28/springboot/SpringBoot%E9%9B%86%E6%88%90Swagger2%E6%9E%84%E5%BB%BARESTfulAPI%E6%96%87%E6%A1%A3/
• 版权声明：本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 彭超 | Blog！