凡图科技

主题

fine-doc模块 ​

依赖

  • pom.xml
xml
<!--fine-doc-->
<dependency>
    <groupId>cn.finemap</groupId>
    <artifactId>fine-doc</artifactId>
    <version>${fine.version}</version>
</dependency>

配置

  • src/main/resources/application.yml
yaml
# 引用fine-doc配置
spring:
  profiles:
    include: doc
# springdoc-openapi项目配置
springdoc:
  # openapi分组
  group-configs:
    - group: 'fine案例'
      # 要匹配组的路径列表
      paths-to-match: '/**'
      # 要扫描的包列表(逗号分隔)
      packages-to-scan: cn.finemap.example
knife4j:
  # 开启生产环境屏蔽
  production: false
  
# openapi info提示信息
fine :
  doc:  
    info:
      title: 凡图科技-API文档
      description: 凡图科技-API文档
      version: 1.0.0
      contact:
        name: 凡图科技
        url: http://www.finemap.cn
      license:
        name: Apache

创建子模块：fine-doc ​

  • 在fine-parent中创建：fine-doc子模块

fine-doc

  • 创建子模块：New > Module...
  • 添加Knife4j依赖
  • 添加springdoc、Knife4j配置
依赖
  • fine-doc/pom.xml
xml
<dependencies>
    <!-- knife4j -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        <version>${knife4j.version}</version>
    </dependency>
</dependencies>
Knife4j配置application-doc.yml
  • src/main/resources/application-doc.yml
yaml
# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    #自定义swagger前端请求路径
    path: /swagger-ui.html
    # 分组排序：使用增强order属性进行排序
    tags-sorter: order
    # 接口排序：使用增强order属性进行排序
    operations-sorter: order
  api-docs:
    # springdoc提供的实例接口（可以导入 apifox）
    path: /v3/api-docs
    #是否开启文档功能
    enabled: true
  default-flat-param-object: true

# knife4j的增强配置
knife4j:
  # 开启增强配置
  enable: true
  # 开启生产环境屏蔽
  # production: false
  setting:
    # Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
    language: zh-CN
    # 是否显示界面中SwaggerModel功能
    enable-swagger-models: true
    # 重命名SwaggerModel名称,默认：SwaggerModel
    swagger-model-name: 实体类
    # 是否显示界面中"文档管理"功能
    enable-document-manage: true
    # 是否显示Footer，及自定义
    enable-footer: false
    enable-footer-custom: true
    footer-custom-content: Apache License 2.0 | Copyright  2019-2024 [北京凡图科技有限责任公司](http://www.finemap.cn)
  basic:
    # 开启Swagger的Basic认证功能,默认是false
    enable: false
    username: root
    password: finemap

# openapi info提示信息
fine :
  doc:
    info:
      # title: 凡图科技-API文档
      # description: 凡图科技-API文档
      # version: 1.0.0
      contact:
        # name: 凡图科技
        # url: http://www.finemap.cn
      license:
        # name: Apache

维护父工程：fine-parent ​

fine-parent

  • 添加该子模块
  • 在父工程中，管理knife4j版本参数
pom
  • fine-parent/pom.xml
xml
<!-- 版本参数 -->
<properties>
    <!-- fine-doc -->
    <knife4j.version>4.4.0</knife4j.version>
</properties>

fine-doc使用 ​

1.在线访问 ​

swagger 文档默认地址：http://127.0.0.1/swagger-ui.html

Knife4j 文档默认地址：http://127.0.0.1/doc.html

springdoc 实例接口：http://127.0.0.1/v3/api-docs

2.主页 ​

2.1.markdown主页 ​

yaml
# knife4j的增强配置
knife4j:
	setting:
		enable-home-custom: true
    	home-custom-path: classpath:markdown/api-home.md

2.2.OpenAPI主页 ​

java
@Configuration
public class SwaggerConfiguration {

  @Value("${spring.application.name:}")
  private String applicationName;

  @Value("${springdoc.info.title:}")
  private String title;

  @Value("${springdoc.info.description:}")
  private String description;

  @Value("${springdoc.info.version:1.0.0}")
  private String version;

  @Value("${springdoc.info.contact.name:凡图科技}")
  private String contactName;

  @Value("${springdoc.info.contact.url:http://www.finemap.cn}")
  private String contactUrl;

  @Value("${springdoc.info.license.name:Apache}")
  private String licenseName;

  @Bean
  public OpenAPI customOpenAPI() {
      if(ObjectUtils.isEmpty(applicationName)){
          applicationName = "凡图科技";
      }
      if(ObjectUtils.isEmpty(title)){
          title = applicationName;
      }
      if(ObjectUtils.isEmpty(description)){
          description = applicationName + "-API文档";
      }
      return new OpenAPI().info(new Info()
              .title(title)
              .description(description)
              .version(version)
              .contact(new Contact().name(contactName).url(contactUrl))
              .license(new License().name(licenseName))
      );
  }
}

3.注解 ​

案例 ​

接口案例
java
@ApiSupport(author = "凡图科技", order = 1)
@Tag(name = "业务", description = "业务描述")
public class TestController {
    
    @ApiOperationSupport(order = 1)
    @Operation(summary = "通过id查询", description = "返回data数据")
    @Parameters({
            @Parameter(name = "id", description = "主键")
    })
    public Result getData(@RequestParam("id") String id) {
        return new Result("data");
    }
    
    @ApiOperationSupport(order = 2)
    @Operation(summary = "测试接口", description = "返回data数据")
    @Parameters({
            @Parameter(name = "name", description = "名称", required = true, in = ParameterIn.QUERY)
    })
    public Result test(@RequestHeader("token") String token,@Nullable  @RequestParam("name") String name, @RequestBody TestEntity entity) {
        return new Result("data");
    }
}
实体类案例
java
@Schema(name="数据表", description = "数据表")
public class TestEntity {

    @Schema(description = "主键", required = true)
    private String id;

    @Schema(description = "名称", example = "Fine")
    private String name;
}

3.1.控制类 ​

  • 控制类申明 @Tag(name = "业务", description = "业务描述")
  • 控制类排序 @ApiSupport(author = "凡图科技", order = 1)

3.2.接口函数 ​

  • 接口申明 @Operation(summary = "通过id查询", description = "返回data数据")
  • 接口排序 @ApiOperationSupport(order = 1)
java
@Parameters({
	@Parameter(name = "主键", description = "主键")
})
  • 接口额外参数申明 @Parameter(name = "id", description = "主键")

3.3.接口参数 ​

  • 参数允许为空申明 @Nullable
  • 参数不能为空申明 @RequestParam() | @RequestParam(required = true)
  • 参数默认值申明 @RequestParam(defaultValue = "false")
  • 参数实体类申明 @RequestBody 申明:使用raw的json形式场参，所以不能用在GET接口
  • 路径参数申明 @PathVariable

3.4.接口响应 ​

  • 接口响应JSON结构 produces = MediaType.APPLICATION_JSON_VALUE
  • 实体类字段显示忽略 @JsonIgnore：在Result.java的isSuccess()字段

3.5.实体类 ​

  • 实体类申明 @Schema(name="数据表", description = "数据表")
  • 实体类字段申明 @Schema(description = "主键", required = true, example = "1")

4.apifox设置接口来源 ​

  • 导入数据，OpenAPI/Swagger

springdoc 实例接口：http://127.0.0.1/v3/api-docs