SpringBoot2 集成 Swagger2

背景

因为过段时间要帮学妹做毕设。但是学妹学的方向是大前端，而我又不会vue。所以就找了我的同学负责前端的编写，我负责后端的编写。那这样一来，这不就是妥妥的前后分离么。所以我做的不光是把后端的接口写出来，还需要的做的是把接口的地址、参数、返回值类型等一些必要的数据给到我同学，这样才能完成前后端的交互。这就牵扯到了”文档“。最烦的文档。如果在功能的编写过程中不修改接口还好，一旦修改接口。相对应的就是文档也要修改，这就很烦。因为我不擅长写文档。

不过呢，文档这个东西Swagger可以搞定。这样就省去了写文档的步骤，有参数说明的。直接写到注解里去，Swagger会自动生成API的页面，以供查看。

环境

1. JDK：1.8
2. 开发工具：IDEA
3. 使用系统：Windows
4. 目的：制作一个资源共享平台的子功能

代码 Coding

依赖

这里就挑重点的放了，剩下的那些MySQL驱动包、SpringBoot依赖什么的就不放了。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>

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

简单说一些这两个依赖的作用。第一个是springfox-swagger2。springfox的作用是通过注解的形式自动生成API文档，利用这个可以很轻松地编写Restful API。Swagger的主要作用是用于将文档展示出来。

而springfox-swagger-ui的作用是将文档转换成可见的页面，这样的话，哪个接口需要什么参数，会有什么返回值，一目了然。很方便

配置

集成Swagger2需要编写一个配置类，这样在项目运行起来之后，Swagger会自动识别并转换成 HTML供查看。

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestful() {
        return new Docket(DocumentationType.SWAGGER_2)
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false) // 告诉 Swagger 不使用默认的 HTTP 响应信息
                .forCodeGeneration(true)
                .apiInfo(apiInfo()) // 添加一些文档的信息，比如版本、作者信息等，方法在下面定义
                .pathMapping("/")
                .select()     
// Docket 提供的两个拦截接口的方法。apis方法的作用为设置拦截的路径，比如我设置的路径为controller这个包，那么只有这个包下的接口才能通过显示出来。paths方法的作用为设置拦截的具体接口（应该支持正则），我这里设置的是any方法，意思是所有的接口都通过。
            .apis(RequestHandlerSelectors.basePackage("cn.net.bcloud.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("资源共享平台 API") // 设置文档标题
                .description("平台 API 介绍") // 设置文档信息
                .version("1.0") // 设置文档的修改的版本
                .build(); // 创建文档
    }
}

不过，这还没有完。还要在主类上开启Swagger才行。

@EnableSwagger2
public class LinksApplication {

Controller 接口编写

这里就不在赘述各种SpringBoot的注解格式了。主要说明 Swagger 的注解及作用

@Api(value = "资源增删改查控制层")
public class FilesController {

@api 是给FileController类添加描述信息，而@api的属性有value、description和tags等，当然最主要用的就是这几个属性。其他可以自行通过源码查看。tags为类所属的标签，description为类的信息。

而在方法上可以这样添加注释

@ApiOperation(value = "添加文件夹和文件")
@PostMapping(value = "/addDirOrFile")
public Files addDirOrFile(@ApiParam(value = "父节点 ID") @RequestParam("fatherId") String fatherId,
                          @ApiParam(value = "文件信息") Files files) {
    return fileServiceImpl.addDirOrFile(files, fatherId);
}

@ApiOperation为方法说明，其属性与Api中的属性一致，作用也是一样的，只是一个的作用对象是类一个的作用对象是方法。@ApiParam为方法的参数说明，其属性与ApiOperation属性一致。

现在呢，启动项目。在浏览器中输入网址http://localhost:8080/swagger-ui.html就可以看到我们配置的Swagger的信息了。

• ← Previous Post