这是我参与8月更文挑战的第4天，活动详情查看：8月更文挑战
Swagger 简介
Swagger 是一个方便 API 开发的框架，它有以下优点：
- 自动生成在线文档，后端开发人员的改动可以立即反映到在线文档，并且不用单独编写接口文档，减轻了开发负担
- 支持通过
Swagger页面直接调试接口，方便前端开发人员进行测试
配置 Swagger
Swagger 目前有 2.x 和 3.x 两个主流版本，配置略有不同。
- 添加依赖
首先去 Maven 仓库中搜索 springfox 查找依赖的坐标，Swagger 是遵循 OpenAPI 规范的技术，而 springfox 是该技术的一种实现，所以这里要搜 springfox 而不是 swagger。
- 对于
Swagger 2.x，需要在pom.xml中添加两项配置：
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 对于
Swagger 3.x，简化了配置项，只需要在pom.xml中添加一项配置：
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
- 为项目开启
Swagger
- 对于
Swagger 2.x，使用@EnableSwagger2注解开启Swagger功能。
@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {
...
}
- 对于
Swagger 3.x，使用@EnableOpenApi注解开启Swagger功能。
@EnableOpenApi
@SpringBootApplication
public 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;
@Configuration
public class SwaggerConfig {
@Value("${spring.profiles.active:NA}")
private String active;
@Bean
public 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控制器")
@RestController
public class HelloController {
@ApiOperation("展示欢迎信息")
@GetMapping("/hello")
public String hello(@ApiParam("名字") String name) {
return "hello, " + name;
}
}
实体相关注解
@ApiModel：一般放在实体类上面。可以通过value指定别名，不指定时默认为类名。还可以通过description指定详细的描述信息。比如@ApiModel("用户")就将显示用户而不是User。
如果仅仅想指定描述，而不改变原始类名显示，可以写成 @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 = "年龄", example = "18", required = true)
private int age;
@ApiModelProperty(hidden = true)
private double money;
}
2021.08.04
