后端编写Swagger接口管理文档

• 2022 年 8 月 6 日
• 笔记
• javaee

Swagger接口管理文档

访问接口文档的网页：//localhost:8080/swagger-ui/index.html

导入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

编写yaml

SpringBoot 2.6以上版本修改了路径匹配规则，但是Swagger3还不支持，这里换回之前的，不然启动直接报错

spring:
	mvc:
		pathmatch:
      matching-strategy: ant_path_matcher

创建配置类配置swagger信息

这个是配置swagger网页的大文字

@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfoMyself())
                .select()   //开启选择扫描接口功能
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))    //设置swagger只扫描该包下的接口(还可以设置只扫描每个类，某个方法）
                .build();
    }

    private ApiInfo apiInfoMyself(){
        return new ApiInfoBuilder()
                .contact(new Contact("你的名字", "//www.bilibili.com", "javastudy111*@163.com"))
                .title("图书馆里系统——在线api接口文档")
                .description("欢迎各位前端大佬前来访问接口")
                .version("1.1") //自己随便定义这个接口第几版的
                .build();
    }
}

添加具体描述

//为xxxcontroller这个类加注解
@Api(tags = "账户验证接口", description = "包括用户登录、注册、验证码请求等操作。")
@RestController
@RequestMapping("/api/auth")
public class AuthApiController {
    
//为某个接口添加注解
@ApiResponses({
        @ApiResponse(code = 200, message = "邮件发送成功"),  
        @ApiResponse(code = 500, message = "邮件发送失败")   //不同返回状态码描述
})
@ApiOperation("请求邮件验证码")   //接口描述
@GetMapping("/verify-code")
public RestBean<Void> verifyCode(@ApiParam("邮箱地址") @RequestParam("email") String email,//请求参数的描述
                                @ApiParam("邮箱地址") @RequestParam("email") String email){
    
//让swagger忽略每个接口
@ApiIgnore     //忽略此请求映射
@PostMapping("/login-success")
public RestBean<Void> loginSuccess(){
    return new RestBean<>(200, "登陆成功");
}
    
//为实体类添加描述（因为有时候会返回一个实体类，所以需要告诉前端人员这个实体类描述的是啥）
@Data
@ApiModel(description = "响应实体封装类")
@AllArgsConstructor
public class RestBean<T> {

    @ApiModelProperty("状态码")
    int code;
    @ApiModelProperty("状态码描述")
    String reason;
    @ApiModelProperty("数据实体")
    T data;

    public RestBean(int code, String reason) {
        this.code = code;
        this.reason = reason;
    }
}
    

如果有配置多环境，prod生产环境就没必要开启swagger了

springfox:
  documentation:
    enabled: false