博客
关于我
Springboot项目集成Swagger
阅读量:706 次
发布时间:2019-03-21

本文共 3786 字,大约阅读时间需要 12 分钟。

Springfox Swagger 2.x 安装与配置实例

在 Spring Boot 项目中集成 Swagger 以便文档化 API,这是一个强大的工具。以下是详细的配置步骤,帮助您快速上手。

一、安装依赖

首先,我们需要将 Swagger 和 Swagger-UI 显示添加到项目依赖中:

io.swagger
springfox-swagger2
2.9.2
io.swagger
swagger-ui
2.9.2

确保通过 MavenResolver 或相关 Package Repository 获取最新版本。

二、配置 Swagger 文档

为了创建 Swagger 文档,我们需要一个配置类,通常放在 config 包中。

1. 创建 SwaggerConfig 类
import io.swagger.annotations.ApiInfo;import io.swagger.service.ApiInfoBuilder;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.ParameterBuilder;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;import io.swagger.service.ModelRef;import io.swagger.service.Parameter;@ApiInfo(    title = "项目文档示例",    description = "这是一个简单的 API 文档示例",    version = "1.0")@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket api() {        ParameterBuilder parameterBuilder = new ParameterBuilder()            .name("token")            .description("token")            .modelRef(new ModelRef("string"))            .parameterType("header")            .required(false)            .build();        Parameter parameter = parameterBuilder.build();        return new Docket(DocumentationType.SWAGGER_2)            .apiInfo(apiInfo())            .select()            .apis(RequestHandlerSelectors.any())            .paths(PathSelectors.any())            .build()            .globalOperationParameters(Collections.singletonList(parameter));    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()            .title("项目文档示例")            .description("这是一个简单的 API 文档示例 1.0")            .termsOfServiceUrl("https://github.com")            .version("1.0")            .build();    }}
2. 配置ApiController

在每个 @RestController 上加入 @Api 注解,可以添加描述和标签。

@RestController@RequestMapping("/api")@Api(tags = "关于测试")public class TestController {    @GetMapping("/test")    @ApiOperation(value = "测试函数")    void test() {        // TODO: 实现逻辑    }}

三、处理拦截器并允许 Swagger

为了确保 Swagger UI 能够正常运行,需要放行相关路径:

import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.InterceptorRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Configurationpublic class WebConfig implements WebMvcConfigurer {    private TokenHelper tokenHelper;    @Override    public void addInterceptors(InterceptorRegistry registry) {        registry.addInterceptor(new TokenInterceptor(tokenHelper))            .addPathPatterns("/**")            .excludePathPatterns("/api/generateToken", "/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");    }}

查看效果

重新启动项目后,访问 http://localhost:8080/swagger-ui.html 即可查看 Swagger 文档。

接口过滤

有些接口需要隐藏,可以在方法上添加 @ApiIgnore 注解。

@RestControllerpublic class LogDebugEnabled {    @GetMapping("/api/logdebug")    @ApiIgnore    void logdebug(@RequestParam String aa, @RequestParam String bb) {        logger.debug("这是 /api/logdebug 接口");        logger.debug("aa:{}", aa);        logger.debug("bb:{}", bb);    }}

实体描述

使用 @ApiModel@ApiModelProperty 注解对 API 中的对象进行描述:

@ApiModel(description = "用户信息")class UserProfile {    @ApiModelProperty(nickname = "用户名", example = "example")    private String username;    @ApiModelProperty(nickname = "密码", example = "examplepass")    private String password;}

以上配置和文档示例已完成,您应该能够轻松集成并使用 Swagger 文档功能进行 API 文档化。

转载地址:http://nfkrz.baihongyu.com/

你可能感兴趣的文章
MySQL 备份 Xtrabackup
查看>>
mysql 多个表关联查询查询时间长的问题
查看>>
mySQL 多个表求多个count
查看>>
mysql 多字段删除重复数据,保留最小id数据
查看>>
MySQL 多表联合查询:UNION 和 JOIN 分析
查看>>
MySQL 大数据量快速插入方法和语句优化
查看>>
mysql 如何给SQL添加索引
查看>>
mysql 字段区分大小写
查看>>
mysql 字段合并问题(group_concat)
查看>>
mysql 字段类型类型
查看>>
MySQL 字符串截取函数,字段截取,字符串截取
查看>>
MySQL 存储引擎
查看>>
mysql 存储过程 注入_mysql 视图 事务 存储过程 SQL注入
查看>>
MySQL 存储过程参数:in、out、inout
查看>>
mysql 存储过程每隔一段时间执行一次
查看>>
mysql 存在update不存在insert
查看>>
Mysql 学习总结(86)—— Mysql 的 JSON 数据类型正确使用姿势
查看>>
Mysql 学习总结(87)—— Mysql 执行计划(Explain)再总结
查看>>
Mysql 学习总结(88)—— Mysql 官方为什么不推荐用雪花 id 和 uuid 做 MySQL 主键
查看>>
Mysql 学习总结(89)—— Mysql 库表容量统计
查看>>