后端编写Swagger接口管理文档

Swagger接口管理文档

访问接口文档的网页：http://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(\"你的名字\", \"https://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

来源：https://www.cnblogs.com/buchizicai/p/16517395.html
本站部分图文来源于网络，如有侵权请联系删除。