博客
关于我
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 order by多个字段排序
查看>>
MySQL Order By实现原理分析和Filesort优化
查看>>
mysql problems
查看>>
mysql replace first,MySQL中处理各种重复的一些方法
查看>>
MySQL replace函数替换字符串语句的用法(mysql字符串替换)
查看>>
mysql replace用法
查看>>
Mysql Row_Format 参数讲解
查看>>
mysql select, from ,join ,on ,where groupby,having ,order by limit的执行顺序和书写顺序
查看>>
MySQL Server 5.5安装记录
查看>>
mysql server has gone away
查看>>
mysql slave 停了_slave 停止。求解决方法
查看>>
MySQL SQL 优化指南:主键、ORDER BY、GROUP BY 和 UPDATE 优化详解
查看>>
MYSQL sql语句针对数据记录时间范围查询的效率对比
查看>>
mysql sum 没返回,如果没有找到任何值,我如何在MySQL中获得SUM函数以返回'0'?
查看>>
mysql Timestamp时间隔了8小时
查看>>
Mysql tinyint(1)与tinyint(4)的区别
查看>>
mysql union orderby 无效
查看>>
mysql v$session_Oracle 进程查看v$session
查看>>
mysql where中如何判断不为空
查看>>
MySQL Workbench 使用手册:从入门到精通
查看>>