SpringBoot集成Swagger2生成接口文档,妈妈再也不用担心我写API文档了

学习心得 做棵大树 4年前 (2020-04-06) 1830次浏览 0个评论
文章目录[隐藏]

在现在的开发过程中,基本已经全部采用API接口的方式进行系统的开发了,于是乎,在此过程中,一个好的 API 文档便成为了后台与前台进行沟通与开发的关键桥梁。

传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,说实话,这样的工作量并不小,而且十分琐碎,且随着项目的更新会出现以下问题。
- 文档难以维护。
- 接口内容更加复杂,编写效率更低。

Swagger 便是为了解决这一问题,它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:

通过Swagger,我们可以在开发接口的过程中通过使用注解自动生成/更新API接口文档,且在文档页面支持接口的调试。

接下来就简单说一下,如何在SpringBoot中集成Swagger2(2 代表其版本)

引入 Swagger2 依赖

pom.xml 文件

<dependencies>
        <!--Swagger2 在此,个人推荐使用 2.8.0 版本,较为稳定-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

</dependencies>

创建配置文件

Swagger2Config.java java 配置文件


@Configuration // 指定扫描的 api 包路径 @ComponentScan(basePackages = {"cn.beatree.xxx.controller"}) //注解开启 swagger2 功能 @EnableSwagger2 public class Swagger2Config { @Value("${swagger2.enable}") boolean enable; // 配置文件中通过值注入控制生产环境与开发环境下的启用状态 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .enable(enable) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("ANONVOTE | Swagger API文档")//标题 .description("description: ANONVOTE | Swagger API文档")//描述 .contact("BEATREE")//作者信息 .version("1.0.0")//版本号 .build(); } }

application.yml 配置文件

swagger2:
  enable: false #true 启用

@Configuration 注解,指定为配置类,会在SpringBoot启动时进行加载。

@EnableSwagger2 注解来启用Swagger2

成员方法 createRestApi 函数创建 Docket 的 Bean 之后,apiInfo() 用来创建该 Api 的基本信息(这些基本信息会展现在文档页面中)。select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给 Swagger 来展现,本例采用指定扫描的包路径来定义,Swagger 会扫描该包下所有 Controller 定义的 API,并产生文档内容(除了被 @ApiIgnore 指定的请求)。

常用 Swagger 注解

  • @Api:修饰整个类,描述 Controller 的作用
  • @ApiOperation:描述一个类的一个方法,或者说一个接口
  • @ApiParam:单个参数描述
  • @ApiModel:用对象来接收参数
  • @ApiProperty:用对象接收参数时,描述对象的一个字段
  • @ApiResponse:HTTP 响应其中 1 个描述
  • @ApiResponses:HTTP 响应整体描述
  • @ApiIgnore:使用该注解忽略这个 API
  • @ApiError :发生错误返回的信息
  • @ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
  • @ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

举个栗子

@RestController
@Transactional    // 事务注解,实现回滚
@RequestMapping("/api/tlink")
@Api(value = "/api/tlink", tags = "参与者相关接口")
public class TlinkController{


    @GetMapping("/checkCode/{code}")
    @ApiOperation(value = "投票认证码核验接口",
            notes = "该接口用于核验认证码合法性,对于投票主题内容的获取需后续调用 Topic 相关接口。返回值 data 中带有参数 topic & options")
    public JSONObject checkCode(@PathVariable("code") String code){
        ...
    }

}

最后在运行SpringBoot项目之后,通过 服务器地址/swagger-ui.html 访问即可。

需要注意的是,如已添加路径拦截器,需通过.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**") 对 swagger 路径放行。


做棵大树 , 版权所有丨如未注明 , 均为原创丨本网站采用BY-NC-SA协议进行授权 , 转载请注明SpringBoot 集成 Swagger2 生成接口文档,妈妈再也不用担心我写 API 文档了
喜欢 (2)
[欢迎投币]
分享 (0)
关于作者:
一个整天无所事事的,有时候忽然热血的孩子
发表我的评论
取消评论
表情 贴图 加粗 删除线 居中 斜体 签到

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址