【Springboot】swagger后端接口文档

Swagger

作用

• 后端接口文档清晰，及时更新
• 接口可以在线测试

参考资料

• 官网：https://swagger.io/

Swagger2

swagger2和swagger3的区别

https://blog.csdn.net/A2254536570/article/details/121767271
https://blog.csdn.net/qq_35425070/article/details/105347336

Swagger3

参考资料
https://blog.csdn.net/cenrc/article/details/119279683

引入依赖

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

注意springboot2.6启动报错
解决方法：在配置文件中添加

spring:
 mvc:
   pathmatch:
   matching-strategy: ant_path_matcher

在浏览器输入
http://localhost:项目端口号/swagger-ui/index.html
即可看到api页面

通过配置类修改文档UI的内容

也可以通过yml来配置

@Configuration
public class swaggerConfig {

    @Bean
    Docket docket(){
        // 设置 swagger的版本
        return new Docket(DocumentationType.OAS_30)
                // 选择生成接口文档
                .select()
                // 包所在的路径
                .apis(RequestHandlerSelectors.basePackage("org.crc.swagger3.controller"))
                // 当前包下所有接口都生成
                .paths(PathSelectors.any())
                .build()
                // 接口文档初始化，也就是设置接口文档的详细信息，
                .apiInfo(
                    new ApiInfoBuilder()
                        .description("xxx 项目接口文档")
                         // 联系人
                        .contact(new Contact("crc","https://blog.csdn.net/cenrc?spm=1001.2101.3001.5343","2516313840@qq.com"))
                        .version("v1.0")
                        .title("API 测试文档")
                        .license("Apache 2.0")
                        .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                        .build()
                );
    }
}

一些扫描配置项

修改后

只希望swagger在生产环境中使用，不在发布中使用？
根据开发环境，给Docket().enable(false)或者enable(true)

API文档分组

分组，如何多个分组？，我有多个docket就可以有多个.groupName

   @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-public")
                .pathsToMatch("/public/**")
                .build();
    }
  
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-admin")
                .pathsToMatch("/admin/**")
                .build();
    }

配置多个组

就是有很多个docket，

效果：

注解

参考资料
https://blog.csdn.net/qq_35425070/article/details/105347336

实体类相关

api方法的返回值类型相关的实体类都会被扫描
@Schema

注意要有set和get

public class Result {
    @Schema(description = "状态码")
    private Integer code;
    @Schema(description = "消息")
    private String message;
    @Schema(description = "数据")
    private Object data;

控制类相关

@Operation（）用于方法
等

注意value和description，一个注解可能有多个参数，表示为不同的形式

@Operation(description ="获取文件列表")
    @GetMapping("/fileList")
    public Result getFileList(){
        logger.info("查询文件列表");
        List<FilePO> fileList = fileService.selectFileList();
        return  new Result(201,"文件列表查询成功",fileList);
    }

在线测试

点击“try it out ”,输入相关参数，即可在线测试接口