深度剖析非侵入式API文档生成神器Smart-Doc，告别注解繁琐的开发过程

2024-02-19 20:58:13

从应用程序开发人员的角度来看，通过Swagger系列可以快速生成API文档，但这些工具都需要在接口上添加注解，属于侵入式方式。那么，有没有一种非侵入式的API文档生成方式呢？本文将介绍一种通过注释生成文档的工具——Smart-Doc，它无需在接口上添加任何注解，即可根据代码自动生成API文档，让开发人员专注于业务代码，提升开发效率。

Smart-Doc简介

Smart-Doc是一个基于Spring Boot的开源项目，它能够自动扫描SpringBoot项目的代码，根据方法上的注释生成API文档。Smart-Doc提供了丰富的注释类型，包括@Api、@ApiOperation、@ApiParam等，这些注释可以帮助Smart-Doc解析方法的详细、参数类型、返回值类型等信息。

如何使用Smart-Doc

1. 依赖添加

在SpringBoot项目中添加Smart-Doc的依赖：

<dependency>
    <groupId>com.smart-doc</groupId>
    <artifactId>smart-doc</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

2. 开启Smart-Doc

在application.yml文件中配置Smart-Doc的开关：

smart-doc:
  enable: true

3. 使用注释生成文档

Smart-Doc支持通过注释生成文档。下面列举一些常用的注释：

@Api：用于控制器，它可以通过description属性指定控制器的描述。
@ApiOperation：用于描述方法，它可以通过value属性指定方法的描述。
@ApiParam：用于描述方法的参数，它可以通过name属性指定参数的名称，通过type属性指定参数的类型，通过description属性指定参数的描述。
@ApiResponse：用于描述方法的返回值，它可以通过code属性指定返回状态码，通过message属性指定返回消息。