Spring Boot中使用 Swagger2 自动构建API文档

Swagger2

https://github.com/swagger-api/swagger-ui

提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

构建RESTful API

在使用Swagger2前我们需要有一个RESTful API的项目. Spring-Boot创建RESTful API项目非常的方便和快速,这里不再介绍如何创建

添加Swagger2依赖

在pom.xml文件中加入以下依赖:

<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>
 <!-- 文件上传 -->
<dependency>
    <groupId>commons-fileupload</groupId>
    <artifactId>commons-fileupload</artifactId>
    <version>1.3.2</version>
</dependency>

创建Swagger2的Java配置类

通过@Configuration注解，表明它是一个配置类，@EnableSwagger2 注解开启swagger2。apiInfo() 方法配置一些基本的信息。createRestApi() 方法指定扫描的包会生成文档,默认是显示所有接口,可以用@ApiIgnore注解标识该接口不显示。

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxx.web"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用 Swagger2 自动构建API文档")
                .description("API文档")
                .version("1.0")
                .build();
    }

}

代码说明：

通过@Configuration注解，让Spring来加载该类配置。

通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现。

本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

Kotlin开发者社区

专注分享 Java、 Kotlin、Spring/Spring Boot、MySQL、redis、neo4j、NoSQL、Android、JavaScript、React、Node、函数式编程、编程思想、"高可用，高性能，高实时"大型分布式系统架构设计主题。

High availability, high performance, high real-time large-scale distributed system architecture design。

分布式框架：Zookeeper、分布式中间件框架等 分布式存储：GridFS、FastDFS、TFS、MemCache、redis等 分布式数据库：Cobar、tddl、Amoeba、Mycat 云计算、大数据、AI算法 虚拟化、云原生技术 分布式计算框架：MapReduce、Hadoop、Storm、Flink等 分布式通信机制：Dubbo、RPC调用、共享远程数据、消息队列等 消息队列MQ：Kafka、MetaQ，RocketMQ 怎样打造高可用系统：基于硬件、软件中间件、系统架构等一些典型方案的实现：HAProxy、基于Corosync+Pacemaker的高可用集群套件中间件系统 Mycat架构分布式演进 大数据Join背后的难题：数据、网络、内存和计算能力的矛盾和调和 Java分布式系统中的高性能难题：AIO，NIO，Netty还是自己开发框架？ 高性能事件派发机制：线程池模型、Disruptor模型等等。。。

合抱之木，生于毫末；九层之台，起于垒土；千里之行，始于足下。不积跬步，无以至千里；不积小流，无以成江河。