Swagger在springboot2和3的配置和使用

最新推荐文章于 2024-07-09 12:36:51 发布

FL不凡

最新推荐文章于 2024-07-09 12:36:51 发布

阅读量996

点赞数 22

分类专栏：后端文章标签： spring boot

本文链接：https://blog.csdn.net/sq91fra/article/details/139337585

版权

后端专栏收录该内容

5 篇文章 0 订阅

订阅专栏

springboot3配置(knife4j)

使用swagger

常用注释

注意事项

springboot2配置

使用swagger

添加依赖：

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-spring-web</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

添加配置类

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置swagger信息 apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人XXX","http://localhost:8080","14019524@qq.com");
        return new ApiInfo(
                "XX项目的swagger",
                "XX项目的swagger",
                "1.0",
                "http://localhost:8080",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

swagger文档访问http://localhost:8080/swagger-ui.html

配置扫描接口

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了swagger的bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否出在自己设定的环境当中 我们想要在测试环境中使用 不要在发布环境中使用
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        //enable设置swagger是否启动  目前是由外部环境所配置
        .enable(flag)
        .select()
        //RequestHandlerSelectors  配置要扫描接口的方式
        //basePackage 指定要扫描的包
        //any()扫描全部
        //none()不扫描
        //withClassAnnotation 扫描类上的注解  参数是一个注解反射对象
        //withMethodAnnotation 扫描方法上的注解  参数是一个注解反射对象
        //下面代码表示只扫描“com.hty.controll”包下的类，即只提供该包下的API
        .apis(RequestHandlerSelectors.basePackage("com.hty.controller"))
        //paths()  过滤什么路径
        //ant()  过滤的路径
        //下面的代码表示只对“/hty/”开头的请求提供API（不太确定是否正确）
        //                .paths(PathSelectors.ant("/hty/**"))
        .build();
    }
    //配置swagger信息 apiInfo
    private ApiInfo apiInfo(){
        Contact contact = new Contact("hty","http://localhost:8080","1156388927@qq.com");
        return new ApiInfo(
            "hty的swagger",
            "hty的swagger",
            "1.0",
            "http://localhost:8080",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
    }
}

配置API文档的分组

修改Docket中的groupName属性即可，若要配置多个组，就需要多个Docket

@Configuration
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("group4");
    }
}

添加注释

给实体类加文档注释


@ApiModel("用户实体类")//给类加一个api注释
public class User {
    @ApiModelProperty("用户名")//给字段加一个api注释
    private String name;
    @ApiModelProperty("密码")//给字段加一个api注释
    private String password;
}

给Controller加文档注释

//给一个controller的方法加注释
@ApiOperation("Hello控制类")

给参数加文档注释


public String hello(@ApiParam("用户名") String username){
    return "hello";
}

springboot3配置(knife4j)

使用knife4j增强swagger

springboot3.x对应knife4j需要使用OpenAPI3

使用swagger

1.导入依赖（SpringBoot3）

<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.5.0</version>
        </dependency>

配置yaml：

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/swagger-ui.html会自动重定向到swagger页面
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.fl.boot.controller # 扫描的包，注意改成自己的包
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true    #开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
    swagger-model-name: 实体类   #重命名SwaggerModel名称,默认
  #开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # Basic认证用户名
    username: fl
    # Basic认证密码
    password: 123456

配置类

@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public GroupedOpenApi adminApi() {      // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                .group("admin-api")         // 分组名称
                .pathsToMatch("/**")  // 接口请求路径规则
                .build();
    }
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                // 基本信息配置
                .info(new Info()
                        // 标题
                        .title("水好物项目接口文档")
                        // 描述Api接口文档的基本信息
                        .description("说明")
                        // 版本
                        .version("v1")
                        // 设置OpenAPI文档的联系信息，包括联系人姓名为"robin"，邮箱为"robin@gmail.com"。
                        .contact(new Contact().name("fl").email("fl@gmail.com"))
                        // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    }
}

完成配置后，就可以访问下面页面：

http://ip:port/doc.html：这是 Knife4j 提供的文档界面，是 Swagger增强版本，它提供了一个更加友好和功能丰富的 UI 来展示 API 文档。这个界面通常包含了 API 的详细信息，包括可用的路径、操作、参数、请求体、响应等，并且提供了一些交互式功能，如 API 的测试。不过我们一般使用专门的接口测试工具进行API的测试。
http://ip:port/swagger-ui.html：这是原始的 Swagger UI 界面，也提供了 API 的详细信息，包括路径、操作、参数等，并且允许用户直接在界面上测试 API。
http://ip:port/v3/api-docs：这个 URL 提供了 OpenAPI 3 规范的 JSON 格式定义，是 API 文档的原始数据，通常由后端服务生成，包含了 API 的所有详细信息，包括路径、操作、参数、请求体、响应等。Swagger UI 和 Knife4j 会解析这个 JSON 文件来展示用户友好的界面。可以使用该地址导入postman等接口测试工具进行接口测试。

Knife4j 文档界面:

Swagger UI 界面:

JSON 格式定义:

常用注释

常用注解：

@OpenAPIDefinition：用于定义 API 的基本信息，如标题、版本、联系人等。
@Info：与 @OpenAPIDefinition 配合使用，提供 API 的详细信息。
@Server：定义 API 的服务器信息，包括 URL、描述等。
@Operation：用于描述一个 API 操作（方法），包括操作ID、摘要、详细描述等。
@Parameter：描述 API 操作的参数，可以是路径参数、查询参数、请求体等。
@RequestBody：用于描述请求体，可以指定内容类型和请求体的 schema。
@ApiResponse：描述 API 操作的响应，包括状态码、原因、响应体的 schema 等。
@ApiResponses：包含多个 @ApiResponse 注解，用于描述多个可能的响应。
@Tag：用于给 API 操作分组，可以定义标签的名称和描述。
@SecurityRequirement：定义 API 的安全要求，通常用于指定 OAuth2 安全方案。
@SecurityScheme：定义 API 的安全方案，如 API 密钥、HTTP 基本认证等。
@Schema：用于定义对象的 schema，可以指定属性、类型、格式等。
@Components：用于定义可重用的 schema、参数、响应等组件。

其他版本配置详见官网

链接

注意事项

注意，如果需要使用拦截器，千万不要继承WebMvcConfigurationSupport类，否则会导致swagger配置无效。因为WebMvcConfigurationSupport类和WebMvcConfigurer冲突

例如下面这样配置会导致swagger配置失效：

@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    @Autowired
    private JwtTokenAdminInterceptor jwtTokenAdminInterceptor;

    /**
     * 注册自定义拦截器
     *
     * @param registry
     */
    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        String[] excludePatterns = new String[]{"/swagger-resources/**", "/webjars/**", "/v2/**","/v3/**", "/swagger-ui.html/**",
                                                "/api", "/api-docs", "/api-docs/**", "/doc.html/**","/doc.html#/**"};
        log.info("开始注册自定义拦截器...");
        registry.addInterceptor(jwtTokenAdminInterceptor)
        .addPathPatterns("/admin/**")
        .excludePathPatterns("/admin/admin/login")
        .excludePathPatterns("/login")
        .excludePathPatterns(excludePatterns)
        ;

    }


}

正确做法是将拦截器和swagger配置写在同一个类中：

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private JwtTokenAdminInterceptor jwtTokenAdminInterceptor;

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

    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
                        .title("水好物项目接口文档")
                        .description("说明")
                        .version("v1")
                        .contact(new Contact().name("fl").email("fl@gmail.com"))
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        String[] excludePatterns = new String[]{"/swagger-resources/**", "/webjars/**","/v3/**", "/swagger-ui.html/**",
                "/api", "/api-docs", "/api-docs/**", "/doc.html/**","/doc.html#/**"};
        registry.addInterceptor(jwtTokenAdminInterceptor)
                .addPathPatterns("/admin/**")
                .excludePathPatterns("/admin/admin/login")
                .excludePathPatterns("/login")
                .excludePathPatterns(excludePatterns);
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
    }
}