SpringBoot2 集成 Swagger2

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-swagger2springfox的作用是通过注解的形式自动生成API文档,利用这个可以很轻松地编写Restful APISwagger的主要作用是用于将文档展示出来。

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的属性有valuedescriptiontags等,当然最主要用的就是这几个属性。其他可以自行通过源码查看。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的信息了。

评论

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×