Spring|Spring Boot中如何使用Swagger详解 SpringBoot中如何使用Swagger详解

Swagger 简介
配置 Swagger

添加依赖
为项目开启 Swagger
创建 SwaggerConfig 配置类
访问 Swagger 前端页面

控制器相关注解

实体相关注解

总结

Swagger 简介
Swagger 是一个方便 API 开发的框架，它有以下优点：

自动生成在线文档，后端开发人员的改动可以立即反映到在线文档，并且不用单独编写接口文档，减轻了开发负担
支持通过 Swagger 页面直接调试接口，方便前端开发人员进行测试

配置 Swagger
Swagger 目前有 2.x 和 3.x 两个主流版本，配置略有不同。

添加依赖
【Spring|Spring Boot中如何使用Swagger详解】首先去 Maven 仓库中搜索 springfox 查找依赖的坐标，Swagger 是遵循 OpenAPI 规范的技术，而 springfox 是该技术的一种实现，所以这里要搜 springfox 而不是 swagger。
对于 Swagger 2.x，需要在 pom.xml 中添加两项配置：

io.springfoxspringfox-swagger22.9.2io.springfoxspringfox-swagger-ui2.9.2

对于 Swagger 3.x，简化了配置项，只需要在 pom.xml 中添加一项配置：

io.springfoxspringfox-boot-starter3.0.0

为项目开启 Swagger
对于 Swagger 2.x，使用 @EnableSwagger2 注解开启 Swagger 功能。

@EnableSwagger2@SpringBootApplicationpublic class SwaggerApplication {...}

对于 Swagger 3.x，使用 @EnableOpenApi 注解开启 Swagger 功能。

@EnableOpenApi@SpringBootApplicationpublic class SwaggerApplication {...}

创建 SwaggerConfig 配置类

对于 Swagger 2.x，实例化 Docket 的时候，需要传入 DocumentationType.SWAGGER_2。
对于 Swagger 3.x，实例化 Docket 的时候，需要传入 DocumentationType.OAS_30。

下面是一份配置模板：

import org.springframework.beans.factory.annotation.Value; 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.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configurationpublic class SwaggerConfig {@Value("${spring.profiles.active:NA}")private String active; @Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)// OAS_30.enable("dev".equals(active))// 仅在开发环境开启Swagger.apiInfo(apiInfo()).host("http://www.example.com")// Base URL.select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).paths(PathSelectors.any()).build(); }private ApiInfo apiInfo() {return new ApiInfoBuilder().title("API文档").description("这是描述信息").contact(new Contact("张三", null, null)).version("1.0").build(); }}

访问 Swagger 前端页面

对于 Swagger 2.x，访问 http://localhost:8080/swagger-ui.html
对于 Swagger 3.x，访问 http://localhost:8080/swagger-ui/

控制器相关注解 @Api：将一个类标记为 Swagger 资源，一般放在 Controller 类上面，通过 tags 指定描述信息，比如 @Api(tags="用户管理")。
@ApiOperation：本注解放在 Controller 方法上面，描述该方法的作用。
@ApiParam：本注解放在 Controller 方法的形参前面，可以描述参数的作用，比如 @ApiParam("用户名") String username。可以使用 value 指定描述信息，通过 required = true 指定必需传递该参数。

package com.example.swagger.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @Api(tags = "Hello控制器")@RestControllerpublic class HelloController {@ApiOperation("展示欢迎信息")@GetMapping("/hello")public String hello(@ApiParam("名字") String name) {return "hello, " + name; }}

文章图片

实体相关注解

@ApiModel：一般放在实体类上面。可以通过 value 指定别名，不指定时默认为类名。还可以通过 description 指定详细的描述信息。比如 @ApiModel("用户") 就将显示用户而不是 User。

![](cdn.jsdelivr.net/gh/jpch89/P… 在 Spring Boot 中使用 Swagger 00.png)
如果仅仅想指定描述，而不改变原始类名显示，可以写成 @ApiModel(description = "用户")。

@ApiModelProperty：一般放在实体类的成员变量上面，通过 value 指定描述信息，example 指定示例数据，required = true 指定该参数是必需的，hidden = true 用于隐藏该字段，不会在 API 文档中显示。

package com.example.swagger.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data@ApiModel(description = "用户")public class User {@ApiModelProperty("用户名")private String username; @ApiModelProperty("密码")private String password; @ApiModelProperty(value = "https://www.it610.com/article/年龄", example = "18", required = true)private int age; @ApiModelProperty(hidden = true)private double money; }