SpringBoot实现自动生成接口文档

发表于 |

前言

需要使用knife4j这个框架来实现我们的需求, 这里我使用的是Gradle构建环境, 具体步骤如下

实现步骤

  1. 添加依赖

    1
    implementation "com.github.xiaoymin:knife4j-spring-boot-starter:2.0.9"

  2. 定义配置类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    @Configuration
    @EnableSwagger2WebMvc
    open class SwaggerConfiguration : WebMvcConfigurer{
        override fun addResourceHandlers(registry: ResourceHandlerRegistry?) {}

        // 创建Docket存入容器，Docket代表一个接口文档
        @Bean
        open fun webApiConfig(): Docket? {
            return Docket(DocumentationType.SWAGGER_2) // 创建接口文档的具体信息
                .apiInfo(webApiInfo()) // 创建选择器，控制哪些接口被加入文档
                .select() // 指定@ApiOperation标注的接口被加入文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation::class.java))
                .build()
        }

        // 创建接口文档的具体信息，会显示在接口文档页面中
        private fun webApiInfo(): ApiInfo? {
            return ApiInfoBuilder() // 
                .title("文档标题") // 
                .description("文档描述") 
                .version("1.0")// 版本
                .contact(Contact("联系人信息", "http://baidu.com", "baidu@qq.com")) // 版权
                .license("版权地址") 
                .licenseUrl("http://www.baidu.com")
                .build()
        }
    }

  3. 给Controller添加文档注解

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    @Api(tags = ["文件管理"])
    @ApiSupport(author = "开发者名称", order = 1)
    @CrossOrigin
    @RestController
    @RequestMapping("/file")
    class FileController {


        @Autowired
        lateinit var service: FileService
        @ApiOperation(value = "文件上传", notes = "这是注释")
        @PostMapping(value = ["/upload"])
        fun uploadFile(
            @RequestParam(value = "file", required = true) file: MultipartFile,
        ): BaseEntity<String> {
            return try {
                val url = service.uploadFile(file)
                BaseEntity(data = url)
            } catch (e: Exception) {
                BaseEntity(code = 505, msg = e.message.orEmpty(), data = "")
            }

        }

    }

  4. 在application.yml配置文件中对knife4j进行相关配置

    1
    2
    3
    4
    5
    6
    7
    knife4j:
      enable: true #开启文档自动生成功能
      production: false # 生产版本时 无权限访问
      basic: # 设置访问密码
        enable: false
        username: abc
        password: 123

  5. 运行工程, 查看文档

    浏览器输入http://ip:端口/doc.html查看自动生成的文档, 如下:

    image-20230410114636451

文档参考

官方文档: 点击进入

本文为作者原创转载时请注明出处 谢谢

乱码三千 – 点滴积累 ,欢迎来到乱码三千技术博客站

0%