spring boot swagger knife4j使用

2024-01-26 23:23 youxin 阅读(175) 评论(0) 编辑收藏举报

Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于openApi3），这篇文章将介绍如何在 java 中使用 OpenApi3（swagger3）以及与swagger2的对比。

1.基本介绍

1.1 Open API

OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

1.2 Swagger

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）。swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。

1.3 SpringFox

SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，都未支持 OpenAPI3 标准。

补充：2020.7.14 发布了 3.0 支持 OpenAPI3，github 发布记录但官网对 3.0 版本相关文档未完善，还是只有 swagger 2.0 相关的。
升级到 OpenAPI3（java 中 swagger1.x 对应 OpenAPI2、swagger 2.x对应OpenAPI3）官方文档

1.4 swagger3 相关特性

支持 Spring 5，Webflux（仅请求映射支持，尚不支持功能端点）、Spring Integration
官方在 spring boot 的自动装配 pringfox-boot-starter 以后可以直接依赖一个 dependency
与swagger2.0更好的规范兼容性
支持OpenApi 3.0.3
轻依赖 spring-plugin，swagger-core

1.5 SpringDoc

SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

该组织下的项目支持swagger页面Oauth2登录（Open API3的内容），相较 SpringFox来说，它的支撑时间更长，无疑是更好的选择。但由于国内发展较慢，在国内不容易看到太多有用的文档，不过可以访问它的官网。它的使用了 swagger3（OpenAPI3），但 swagger3 并未对 swagger2 的注解做兼容，不易迁移，也因此，名气并不如 spring fox。

2.开始使用

2.1 从 spring-fox 迁移到 springdoc

依赖变更
pom.xml 里去掉 springfox 或者 swagger 的依赖，添加springdoc-openapi-ui。

<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.2</version>
</dependency>

2.2 Swagger3与 Swagger2注解对比使用

使用 swagger3 注解代替 swagger2 的（为可选项）

Swagger3	Swagger2	注解说明
@Tag(name = “接口类描述”)	@Api	Controller 类
@Operation(summary =“接口方法描述”)	@ApiOperation	Controller 方法
@Parameters	@ApiImplicitParams	Controller 方法
@Parameter(description=“参数描述”)	@ApiImplicitParam @ApiParam	Controller 方法上 @Parameters 里 Controller 方法的参数
@Parameter(hidden = true) @Operation(hidden = true) @Hidden	@ApiIgnore	排除或隐藏api
@Schema	@ApiModel @ApiModelProperty	DTO实体 DTO实体属性

Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。

@ApiParam和@ApiImplicitParam的功能是相同的，但是@ApiImplicitParam的适用范围更广。在非JAX-RS的场合（比如使用servlet提供HTTP接口），只能使用@ApiImplicitParam进行参数说明。我认为，这是因为接口并不显式展示入参的名称，所以没有地方去使用@ApiParam，只能在接口的方法声明下方写@ApiImplicitParam

2.3 Api 分组配置

Swagger2 配置：

@Bean
    public Docket publicApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
             .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
                .paths(PathSelectors.regex("/api/v1/public.*"))
                .build()
                .groupName("spring-app-public")
                .apiInfo(apiInfo());
    }
Swagger3配置：

@Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .setGroup("spring-app-public")
                .pathsToMatch("/api/v1/public/**")
                .build();
    }
Swagger3用配置文件替代代码配置：

springdoc.packagesToScan=package1, package2

springdoc.pathsToMatch=/api/v1/public/**

swagger2 使用：

            <!-- knife4j 接口文档工具 -->
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-spring-boot-starter</artifactId>
                <version>2.0.9</version>
            </dependency>
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>knife4j-springdoc-ui</artifactId>
                <version>3.0.3</version>
            </dependency>

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("xx@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

https://doc.xiaominfo.com/docs/action/springboot

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

knife4j的增强配置

Knife4j自2.0.6版本开始,将目前在Ui界面中一些个性化配置剥离,开发者可以在后端进行配置，并且提供的knife4j-spring-boot-strater组件自动装载

spring.factories配置如下：

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration

 

在Spring Boot配置文件中,完整的配置如下:

重要提示

Knife4j 自4.0版本，配置属性元数据全部改由spring-boot-configuration-processor自动生成，因此之前版本的驼峰命名全部修改成了横杠(-)代替

knife4j:
  enable: true
  documents:
    -
      group: 2.X版本
      name: 接口签名
      locations: classpath:sign/*
  setting:
    language: zh-CN
    enable-swagger-models: true
    enable-document-manage: true
    swagger-model-name: 实体类列表
    enable-version: false
    enable-reload-cache-parameter: false
    enable-after-script: true
    enable-filter-multipart-api-method-type: POST
    enable-filter-multipart-apis: false
    enable-request-cache: true
    enable-host: false
    enable-host-text: 192.168.0.193:8000
    enable-home-custom: true
    home-custom-path: classpath:markdown/home.md
    enable-search: false
    enable-footer: false
    enable-footer-custom: true
    footer-custom-content: Apache License 2.0 | Copyright  2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)
    enable-dynamic-parameter: false
    enable-debug: true
    enable-open-api: false
    enable-group: true
  cors: false
  production: false
  basic:
    enable: false
    username: test
    password: 12313
 

在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解

注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

https://doc.xiaominfo.com/docs/features/enhance

示例：

# https://doc.xiaominfo.com/knife4j
knife4j:
  # 开启增强配置
  enable: true
  # 是否开启生产环境屏蔽   true:关闭swagger，false:开启swagger
  production: false
  basic:
    # 是否开启认证
    enable: false
    # Basic认证用户名
    username: admin
    # Basic认证密码
    password: 123456

会员力量，点亮园子希望

刷新页面返回顶部

有心故我在