博客
关于我
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中interactive_timeout和wait_timeout的区别
查看>>
mysql中int、bigint、smallint 和 tinyint的区别、char和varchar的区别详细介绍
查看>>
mysql中json_extract的使用方法
查看>>
mysql中json_extract的使用方法
查看>>
mysql中kill掉所有锁表的进程
查看>>
mysql中like % %模糊查询
查看>>
MySql中mvcc学习记录
查看>>
mysql中null和空字符串的区别与问题!
查看>>
MySQL中ON DUPLICATE KEY UPDATE的介绍与使用、批量更新、存在即更新不存在则插入
查看>>
MYSQL中TINYINT的取值范围
查看>>
MySQL中UPDATE语句的神奇技巧,让你操作数据库如虎添翼!
查看>>
Mysql中varchar类型数字排序不对踩坑记录
查看>>
MySQL中一条SQL语句到底是如何执行的呢?
查看>>
MySQL中你必须知道的10件事,1.5万字!
查看>>
MySQL中使用IN()查询到底走不走索引?
查看>>
Mysql中使用存储过程插入decimal和时间数据递增的模拟数据
查看>>
MySql中关于geometry类型的数据_空的时候如何插入处理_需用null_空字符串插入会报错_Cannot get geometry object from dat---MySql工作笔记003
查看>>
mysql中出现Incorrect DECIMAL value: '0' for column '' at row -1错误解决方案
查看>>
mysql中出现Unit mysql.service could not be found 的解决方法
查看>>
mysql中出现update-alternatives: 错误: 候选项路径 /etc/mysql/mysql.cnf 不存在 dpkg: 处理软件包 mysql-server-8.0的解决方法(全)
查看>>