@transactional 接口_SpringBoot集成Swagger2生成接口文档，妈妈再也不用担心我写API文档了

在现在的开发过程中，基本已经全部采用 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 路径放行。