背景
因为过段时间要帮学妹做毕设。但是学妹学的方向是大前端,而我又不会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
的信息了。