背景
因为过段时间要帮学妹做毕设。但是学妹学的方向是大前端，而我又不会vue。所以就找了我的同学负责前端的编写，我负责后端的编写。那这样一来，这不就是妥妥的前后分离么。所以我做的不光是把后端的接口写出来，还需要的做的是把接口的地址、参数、返回值类型等一些必要的数据给到我同学，这样才能完成前后端的交互。这就牵扯到了”文档“。最烦的文档。如果在功能的编写过程中不修改接口还好，一旦修改接口。相对应的就是文档也要修改，这就很烦。因为我不擅长写文档。
不过呢，文档这个东西Swagger可以搞定。这样就省去了写文档的步骤，有参数说明的。直接写到注解里去，Swagger会自动生成API的页面，以供查看。
环境
- JDK：1.8
- 开发工具：IDEA
- 使用系统：Windows
- 目的：制作一个资源共享平台的子功能
代码 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的信息了。