Spring boot 使用 Swagger3 生成API接口文档

• 一、导入依赖
• 二、编写相关类
• • 1.application.yml
  • 2.SwaggerProperties 类
  • 3.Swagger配置类
  • 4. Controller
  • 5. 实体类User
  • 6. 常用注解
• 三、Swagger管理页面
• 四、使用knife4j优化体验
• • 1. 导入依赖
  • 2. 访问网址

本文是Swagger3 相关笔记总结，方便自己以后复习，同时也希望对大家有所帮助。

 		
        
            io.springfox
            springfox-boot-starter
            3.0.0
        

server:
  port: 8089

spring:
  application:
    name: bbx-swagger
  # ===== 避免spring boot版本和swagger版本不一致报错 ===== #
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

# ===== 自定义swagger配置 ===== #
swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: v1.0
  application-description: springfox swagger 3.0 Demo
  try-host: http://localhost:${server.port}

@Component
@ConfigurationProperties("swagger")
@Data
public class SwaggerProperties {

    
    private Boolean enable;

    
    private String applicationName;

    
    private String applicationVersion;

    
    private String applicationDescription;

    
    private String tryHost;
}

@Configuration
@EnableOpenApi //swagger3启动注释
public class SwaggerConfig {
    @Autowired
    private SwaggerProperties swaggerProperties;

    @Bean
    public Docket userDocket(){
        return new Docket(DocumentationType.OAS_30)
                //定义是否开启swagger
                .enable(swaggerProperties.getEnable())
                .groupName("bbx")
                //api展示信息
                .apiInfo(apiInfo())
                //接口调试地址
                .host(swaggerProperties.getTryHost())
                //过滤条件
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bbx.swagger.controller"))
                .build();
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                //定义是否开启swagger
                .enable(swaggerProperties.getEnable())
                .groupName("fft");
    }

    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("bbx","https://blog.csdn.net/BBQ__ZXB?type=blog","1101249732@qq.com");
        return new ApiInfo(
                swaggerProperties.getApplicationName() + "APi Doc",
                swaggerProperties.getApplicationDescription(),
                swaggerProperties.getApplicationVersion(),
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

@RestController
@RequestMapping("/user")
@Api(tags = "用户接口类")
//@Tag(name = "用户管理", description = "用户数据增删改查") 不生效
public class UserController {

    @Autowired
    private UserService userService;


    @ApiOperation("测试接口1") //swagger2
    //@Operation(summary = "测试接口1") //swagger3
    @PostMapping("/show1")
    public String show1(@ApiParam(value = "姓名", required = true, example = "笨笨熊")@RequestBody String name) {
        return "hello," + name;
    }

    @ApiOperation("测试接口2")
    @PostMapping("/show2")
    public String show2(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {
        return "hi," + user.getName();
    }
}

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
//@Schema(name = "用户实体类") 不生效
public class User {

	//swagger3
    @Schema(description = "姓名",required = true,example = "笨笨熊")
    private String name;
    
	//swagger2
    @ApiModelProperty(value = "年龄",required = true,example = "21")
    private Integer age;
}

swagger3的注解与swagger2相差很多，但兼容了swagger2的注解，区别如下：

http://localhost:8089/swagger-ui/index.html

        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            3.0.2
        

http://localhost:8089/doc.html

参考博客：
Swagger3 注解使用（Open API 3）