Spring Boot集成Swagger

@(Swagger)[swagger, springfox, springboot]

Spring Boot集成Swagger
- 前言
- 基本概述
- 案例
  - 引入依赖
  - Swagger配置
  - 配置方式
    - 基本概述
    - 控制器
    - 统一响应类
    - 用户Model
    - 文档界面
- 源码
- 参考信息

前言

为了完成项目自带文档的需求，花了一定的时间研究Spring Boot集成Swagger。看了官方文档和一些博客，差不多搭出一个比较通用的架子。

文末会分享出案例项目。

基本概述

本文使用Spring Boot+Spring Fox的方式集成Swagger框架。

案例

引入依赖

<properties><swagger.version>2.7.0</swagger.version>
</properties>
<dependencies><!-- swagger2 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>${swagger.version}</version></dependency><!-- swagger2 ui --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>${swagger.version}</version></dependency>
</dependencies>

Swagger配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.switchvov.swagger")).paths(PathSelectors.any()).build().securitySchemes(securitySchemes()).securityContexts(securityContexts());}/*** 配置认证模式*/private List<ApiKey> securitySchemes() {return newArrayList(new ApiKey("Authorization", "Authorization", "header"));}/*** 配置认证上下文*/private List<SecurityContext> securityContexts() {return newArrayList(SecurityContext.builder().securityReferences(defaultAuth()).forPaths(PathSelectors.any()).build());}private List<SecurityReference> defaultAuth() {AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];authorizationScopes[0] = authorizationScope;return newArrayList(new SecurityReference("Authorization", authorizationScopes));}/*** 项目信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("Swagger测试项目 RESTful APIs").version("1.0").build();}
}

配置方式

基本概述

Swagger官方Wiki 注解
swagger2常用注解说明
swagger注释API详细说明

PS：以上几篇文章已经将Swagger注解的使用方式及作用阐述的非常清楚了。这里只给出代码案例。

PS：springfox-swagger2:2.7.0已经支持泛型返回对象。
注意：千万不要在@ApiOperation注解里限定response()，让框架推断类型就行了。

控制器

@RestController
@RequestMapping(value = "/user", produces = "application/json")
@Api(value = "User", tags = {"User"}, description = "用户相关")
public class UserController {@Autowiredprivate UserService userService;@GetMapping("/{id}")@ApiOperation(value = "使用ID查询用户")@ApiImplicitParams({@ApiImplicitParam(value = "ID", name = "id", dataType = "int", paramType = "path", required = true, defaultValue = "1")})@ApiResponses({@ApiResponse(code = 400, message = "请求参数有误"),@ApiResponse(code = 401, message = "未授权"),@ApiResponse(code = 403, message = "禁止访问"),@ApiResponse(code = 404, message = "请求路径不存在"),@ApiResponse(code = 500, message = "服务器内部错误")})public ResponseResult<User> getById(@PathVariable("id") Integer id) {User user = userService.getById(id);return ResponseResult.successWithData(user);}@PostMapping("")@ApiOperation(value = "创建用户")@ApiResponses({@ApiResponse(code = 400, message = "请求参数有误"),@ApiResponse(code = 401, message = "未授权"),@ApiResponse(code = 403, message = "禁止访问"),@ApiResponse(code = 404, message = "请求路径不存在"),@ApiResponse(code = 500, message = "服务器内部错误")})public ResponseResult<User> createUser(@Validated @RequestBody User user) {User dbUser = userService.createUser(user);return ResponseResult.successWithData(dbUser);}
}

统一响应类

@ApiModel(description = "响应对象")
public class ResponseResult<T> {private static final int SUCCESS_CODE = 0;private static final String SUCCESS_MESSAGE = "成功";@ApiModelProperty(value = "响应码", name = "code", required = true, example = "" + SUCCESS_CODE)private int code;@ApiModelProperty(value = "响应消息", name = "msg", required = true, example = SUCCESS_MESSAGE)private String msg;@ApiModelProperty(value = "响应数据", name = "data")private T data;// 省略get、set方法等等，详见源代码
}

用户Model

PS：用户model使用了lombok、jpa、validator，只需要关注@Api开头的注解就行了。

@Data
@Entity(name = "users")
@ApiModel(description = "用户Model")
public class User {@Id@GeneratedValue(strategy = GenerationType.AUTO)@Null(message = "id必须为空")@ApiModelProperty(value = "用户ID", name = "id")private Integer id;@Column@NotBlank(message = "用户名不能为空")@ApiModelProperty(value = "用户名", name = "username", required = true, example = "zhaoliu")private String username;@Column@NotBlank(message = "密码不能为空")@ApiModelProperty(value = "密码", name = "password", required = true, example = "123456")private String password;
}

文档界面

源码

GitHub：swagger-demo

参考信息

SpringFox官网
Swagger官方Wiki 注解
Spring Boot中使用Swagger2构建强大的RESTful API文档
第四章 springboot + swagger
Spring启动RESTful API文档使用Swagger 2
swagger2常用注解说明
swagger注释API详细说明
Swagger2 添加HTTP head参数
Swagger2 非全局、无需重复输入的Head参数（Token）配置

Spring Boot集成Swagger相关推荐

Spring Boot集成Swagger导入YApi@无界编程
接口APi开发现状现在开发接口都要在类似YApi上写文档,这样方便不同的团队之间协作,同步更新接口,提高效率. 但是如果接口很多,你一个个手工在YApi去录入无疑效率很低. 如果是使用Spring ...
spring boot集成swagger，自定义注解，拦截器，xss过滤，异步调用，定时任务案例...
本文介绍spring boot集成swagger,自定义注解,拦截器,xss过滤,异步调用,定时任务案例集成swagger--对于做前后端分离的项目,后端只需要提供接口访问,swagger提供了接口 ...
Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
Spring Boot集成Swagger UI
一:首先了解一下什么是Swagger UI? Swagger UI 允许任何人(无论是开发团队还是最终消费者)可视化 API 的资源并与之交互,而无需任何实现逻辑.它是根据您的 OpenAPI(以 ...
Spring boot :使用 Swagger 2 构建 RESTful APIs
1.美图 2.什么是 Swagger Swagger 是一系列列 RESTful API 的⼯具,通过 Swagger 可以获得项⽬的一种交互式⽂档,客户端 SDK 的⾃动⽣生成等功能. Swagge ...
Spring Boot系列六 Spring boot集成mybatis、分页插件pagehelper
1. 概述本文的内容包括如下内容: Spring Boot集成mybatis Spring Boot集成pagehelper分页插件,定义分页的相关类实现工具类:model转dto,实现数据层和传 ...
6.3 Spring Boot集成mongodb开发
6.3 Spring Boot集成mongodb开发本章我们通过SpringBoot集成mongodb,Java,Kotlin开发一个极简社区文章博客系统. 0 mongodb简介 Mongo 的主 ...
Spring Boot和Swagger UI
我已经一年没有从头开始开发Spring Web应用程序了,如果我不参加QA自动化工程师的培训,那么这段时间甚至会更长. 由于这个原因,我开发了一个示例REST应用程序. 除了Swagger,一切对我来 ...
有手就行的 Spring Boot 集成 Shiro
前言 Apache Shiro 是 Java 的一个安全框架.目前,使用 Apache Shiro 的人越来越多,因为它相当简单,对比 Spring Security,可能没有 Spring Se ...

Spring Boot集成Swagger

Spring Boot集成Swagger

前言

基本概述

案例

引入依赖

Swagger配置

配置方式

基本概述

控制器

统一响应类

用户Model

文档界面

源码

参考信息

Spring Boot集成Swagger相关推荐

最新文章

热门文章