Spring Boot中使用Swagger2构建RESTful API文档

 

 后端开发人员编写接口通常会以整理成文档的形式提供给前端访问或得数据，但是后端整理的restful API文档可能要面对多个开发人员或多个团队，为了减少与其他团队平时开发期间的频繁沟通成本，传统方法我们会创建一份restful API文档来记录所有接口细节 但是创建传统接口文档有很多弊端，例如：

　　1.由于接口众多，并且细节复杂(需要考虑不同 的http请求类型，http头部信息，http请求内容等)，高质量地创建这份文档本身就是件非常慢吃力的事。

　　2.随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然那很容易导致不一致现象

由于Spring Boot能够快速开发、便捷部署等特性，相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因，这些终端会共用很多底层业务逻辑，因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

Spring Boot 整合Swagger2可以很好的解决传统接口文档所带来的很多弊端。

下面详细介绍Spring Boot 整合Swagger2的使用

首先在我们的pom.xml里引入jar依赖：

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

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

对的就是他们没错了

那么接下来编写配置类了，，

package com.luer.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spring.web.plugins.Docket;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Created by shenjianhua on 19/1/18.
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
　　　　　　　　　　//采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API
                //.apis(RequestHandlerSelectors.basePackage("com.zzh.controller"))
                //这里采用包含注解的方式来确定要显示的接口
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("简单优雅的RESTful API风格")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

下面的url就是访问API文档的链接了，当然你得先把项目跑起来，然后换成自己的项目名和自己的项目端口。

//http://localhost:8099/supplychain/swagger-ui.html

Swagger2生产文档的注解详细介绍

swagger2通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiParamImplicitL：一个请求参数
• @ApiParamsImplicit 多个请求参数

举个栗子：

Swagger2不仅仅可以展示接口，还可以用来测试接口..........待续


--------------------------------------------《end》--------------------------------------------