Swagger | SpringMVC+SpringFox+Swagger 实现接口的文档在线自动生成

本文主要讲解的是如何整合swagger2和springmvc,由于项目还在使用的的ssm框架,并且已经实现了前后端分离开发,作为后端开发人员需要给前端开发人员提供接口说明文档以便前端开发.虽然内部有文档,但是对我的api说明也是有必要提供的.

本文目标是先搭建一个简单的Spring MVC应用，然后为Spring MVC整合SpringFox-Swagger以及SpringFox-Swagger-UI，最终，达到Spring MVC对外开放接口API文档化。

---

一. 搭建SpringMVC工程

新建Maven工程,引入Spring所依赖的Jar包,编写Spring-mvc文件,配置web.xml,编写Controller并测试接口.验证Spring MVC是否能正常访问.

使用IDEA正常的搭建一个springmvc项目,我想大家应该都会了,下面主要贴一下相关依赖:

<properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <org.springframework.version>4.2.0.RELEASE</org.springframework.version>
    </properties>

<!-- spring start -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aop</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aspects</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-beans</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context-support</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-expression</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-instrument</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-instrument-tomcat</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jms</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-messaging</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-orm</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-oxm</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-tx</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc-portlet</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-websocket</artifactId>
    <version>${org.springframework.version}</version>
</dependency>
<!-- spring end -->

---

二.整合SpringFox-Swagger

SpringFox已经可以代替Swagger-SpringMVC, 目前SpringFox同时支持Swagger 1.2 和 2.0.
在SpringMVC项目中整合SpringFox-Swagger只需要如下两个步骤既可:

• 1.添加SpringFox-Swagger依赖
• 2.配置swagger(添加SwaggerConfig)

1.添加依赖

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

---

2.配置Swagger

package com.yveshe.conf;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.core.env.Environment;
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.spring.web.paths.RelativePathProvider;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger配置类
 *
 * @author yveshe ([email protected])
 * @create 08 26, 2019
 * @since 1.0.0
 */
@Configuration
@EnableSwagger2
@PropertySource("classpath:api.properties")
public class SwaggerConfig {

    public static final String API_TILE = "api.title";
    public static final String API_DESC = "api.desc";
    public static final String API_VERSION = "api.version";
    public static final String API_SERVICE_URL = "api.service.url";
    public static final String API_BASE_PATH = "api.base.path";
    public static final String API_HOST = "api.host";
    public static final String API_SCAN_PACKAGE = "api.scan.package";

    public static final String API_LICENSE = "api.license";
    public static final String API_LICENSE_URL = "api.license.url";


    @Autowired
    private Environment environment;

    @Bean
    public Docket api() {

        String host = environment.getProperty(API_HOST, "");
        String scanPackage = environment.getProperty(API_SCAN_PACKAGE, "");
        RelativePathProvider pathProvider = new RelativePathProvider(null) {
            @Override
            public String getApplicationBasePath() {
                String basePath = environment.getProperty(API_BASE_PATH, "");
                return basePath;
            }
        };

        return new Docket(DocumentationType.SWAGGER_2).pathProvider(pathProvider).host(host)
                .select()
                .apis(RequestHandlerSelectors.basePackage(scanPackage))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());

        // RequestHandlerSelectors.any()  : 任意的API
    }

    private ApiInfo apiInfo() {
        String title = environment.getProperty(API_TILE, "");
        String desc = environment.getProperty(API_DESC, "");
        String version = environment.getProperty(API_VERSION, "");
        String serviceURL = environment.getProperty(API_SERVICE_URL, "");
        String license = environment.getProperty(API_LICENSE, "");
        String licenseURL = environment.getProperty(API_LICENSE_URL, "");
        return new ApiInfoBuilder()
                .title(title)
                .description(desc)
                .version(version)
                .termsOfServiceUrl(serviceURL)
                .license(license)
                .licenseUrl(licenseURL)
                .build();
    }

}

这里我使用到了Spring的注解特性,将所有关于Swagger的数据采用配置文件的形式配置在api.properties文件中:

api.title=YvesHe Open API Documentation
api.desc=HTTP Open Interface

api.version=1.0.0
api.service.url=http://wwww.yveshe.com

#  不配置默认为发布的项目名称,如果配置了项目的前缀,需要在这里配置修改
api.base.path=/yveshe_api_war_exploded

api.host=localhost:8080

# 配置Swagger扫描的包
api.scan.package=com.yveshe.endpoint

api.license=LICENSE
api.license.url=http://xxx.xxx.com

---

三. 整合SpringFox-Swagger-UI

在SpringMVC项目中整合SpringFox-Swagger-UI也只要如下两个步骤即可:

• 1.添加SpringFox-Swagger-UI依赖
• 2.添加配置

1.添加依赖

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

---

2.添加配置

在添加配置之前，一起来看一下swagger-ui中使用的静态资源文件（如 swagger-ui.html ）放在哪里吧,spingfox-swagger-ui-2.7.0.jar中的 /META-INF/resources/ 下~ 如下图所示：

为了访问swagger-ui.html，我们需要配置对这些静态资源的访问:
在

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
<mvc:resources mapping="/webjars/**"
	location="classpath:/META-INF/resources/webjars/" />

在本文中，可以将其配置在spring-mvc.xml中:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.0.xsd
		http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.0.xsd
		http://www.springframework.org/schema/mvc http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">

    <!-- 默认的注解映射的支持 ,它会自动注册DefaultAnnotationHandlerMapping 与AnnotationMethodHandlerAdapter -->
    <mvc:annotation-driven/>

    <!-- enable autowire 向容器自动注册 -->
    <context:annotation-config/>

    <!-- 设置使用注解的类所在的jar包 -->
    <context:component-scan base-package="com.yveshe"/>
    <bean
            class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter"/>


    <!-- 配置静态资源的访问 -->
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
    <mvc:resources mapping="/webjars/**"
                   location="classpath:/META-INF/resources/webjars/"/>

</beans>

---

如果自己的项目是注解配置风格的,可以考虑使用如下配置(与XML中的配置等效)

package com.yveshe.conf;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

/**
 * 配置静态资源的访问
 *
 * @author yveshe ([email protected])
 * @create 08 26, 2019
 * @since 1.0.0
 */
@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

---

四. 编写接口API代码

效果图:

---

五 .附录: 本文代码下载

https://github.com/YvesHe/yveshe-api

---