java使用knife4j接口文档

原创已于 2024-07-11 14:47:38 修改 · 1k 阅读

本内容遵循CC 4.0 BY-SA版权协议

于 2024-07-09 14:16:39 首次发布

1. 引入依赖

 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
     <version>4.4.0</version>
 </dependency>

2、区分模块

如下面所示，该controller包含整个模块的接口

@Api(tags = "厂家管理")
@RequestMapping("/factory")
@RestController
public class FactoryController {
}

@Api是 swagger-annotations 库中常用的注解，用于对整个 API 或 API 中的一组接口进行分类或分组。这个注解通常用在控制器类（Controller）或接口类上，用来为 Swagger 文档生成器提供额外的信息，帮助组织和分类 API 文档。

3.1 无参接口

无参接口只需添加 @ApiOperation

    @ApiOperation(value = "获取对应型号")
    @GetMapping("/models")
    public ResultVo models() {
        return factoryService.models();
    }

@ApiOperation是 swagger-annotations 库中的注解，用于描述单个接口的作用和功能。这个注解通常用在控制器类中的方法上，用来说明该方法的作用是什么，以及在 Swagger 生成的 API 文档中如何展示这个接口。@ApiOperation 注解有几个常用的属性，其中 value 属性是必需的，用来指定接口的简要描述或作用。除了 value 属性外，还可以通过其他属性来提供更详细的信息，比如 notes、response、responseContainer 等，用来描述接口的响应信息、参数说明等。

3.2 一个参数接口

    @ApiOperation(value = "列表接口")
    @ApiImplicitParam(name = "factoryName", value = "厂家名称", dataType = "String")
    @GetMapping("/list")
    public PageVO<FactoryVo> list(@RequestParam(required = false) String factoryName) {
        return factoryService.list(factoryName);
    }

@ApiImplicitParam 是 swagger-annotations 库中的注解之一，用于描述单个方法参数的信息，这些信息将用于生成 Swagger API 文档。它通常与 @ApiOperation 注解一起使用，用来详细描述接口的输入参数。
@ApiImplicitParam 注解有几个常用的属性：

name：参数名称。
value：参数的描述或说明。
dataType：参数的数据类型。在 Swagger 中，这个属性用来指定参数的数据类型，
基础数据类型：
“String”、“int” 、“long”、“float”、“double”、“boolean”、“byte”、“short”、“char”；
时间类型：
“date”: 表示日期，通常是 YYYY-MM-DD 格式。
“dateTime”: 表示日期和时间，通常是 ISO 8601 格式，如 YYYY-MM-DDTHH:mm:ss.SSSZ。
其他特定类型：
“file”: 文件类型，用于表单上传文件时。
“array”: 数组类型，可以指定数组元素的数据类型，如 “array[string]” 表示字符串数组。
paramType：参数类型，可以是 “query”、“path”、“header”、“body” 或 “form” 等，表示参数在请求中的位置。
required：参数是否是必填的，默认为 false。
defaultValue：参数的默认值。

3.3 多个参数接口

    @ApiOperation(value = "列表接口")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "page", value = "页数", dataType = "int"),
            @ApiImplicitParam(name = "pageSize", value = "每页条数", dataType = "int"),
            @ApiImplicitParam(name = "factoryName", value = "厂家名称", dataType = "String")
    })
    @GetMapping("/list")
    public PageVO<FactoryVo> list(@RequestParam(required = false) Integer page,
                                  @RequestParam(required = false) Integer pageSize,
                                  @RequestParam(required = false) String factoryName) {
        return factoryService.list(page, pageSize, factoryName);
    }

3.4 post请求体接口及参数说明

接口

    @ApiOperation(value = "新增/修改")
    @PostMapping("/save")
    public ResultVo save(@RequestBody FactoryEntity factoryManage) {
        return factoryService.save(factoryManage);
    }

实体类

public class FactoryEntity extends SQBaseEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Column(name = "[ID]", length = 32)
    private Long id;

    /**
     * 排序号
     */
    @ApiModelProperty(value = "排序号")
    @Column(name = "SORT_NUM")
    private Long sortNum;

    /**
     * 厂家编码
     */
    @ApiModelProperty(value = "厂家编码", required = true)
    @Column(name = "FACTORY_CODE")
    private String factoryCode;

    /**
     * 厂家名称
     */
    @ApiModelProperty(value = "厂家名称", required = true)
    @Column(name = "FACTORY_NAME")
    private String factoryName;

@ApiModelProperty 是 Java 中 swagger-annotations 库中的一个注解，用于在 Swagger API 文档中描述接口的属性信息。这个注解通常用在 DTO（Data Transfer Object）或实体类的属性上，用来生成 API 文档，并指定属性的说明、数据类型、是否必需等信息。

4、需要注意的点

使用如上方式进行接口定义，必须将所有的controlle放到同一个包中，不然访问接口文档会报错！！！针对如上问题进行代码优化，添加配置类如下所示:

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger
                .enable(Boolean.TRUE)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.dong.cloud.controller"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }


    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("产品质量数据采集与验收管理系统客户端")
                // 描述
                .description("描述：用于采集处理外协厂家数据")
                // 作者信息
                .contact(new Contact("dongxj", null, null))
                // 版本
                .version("版本号:1.0.0" )
                .build();
    }