Springfox与SpringMvc集成实现接口文档化

2019独角兽企业重金招聘Python工程师标准>>>

准备环境

1. 一个web服务器(我使用的是tomcat、当然nginx都可以)
2. eclipse开发环境使用SpringMvc框架的源码(我使用springfox官网提供的demo)
3. 下载swagger-ui源码

实现目的

1. eclipse中启动后台项目(也可以直接打包war在另一个tomcat中发布)
2. web服务器使用swagger-ui做为前端展示层展示后台基于swagger暴露的接口
3. 后台服务支持跨域请求(项目上线可以关闭)

1. 后台接口演示环境搭建

1.1 项目pom文件对依赖包引用如下：

<properties>
    <jackson2.version>2.5.1</jackson2.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spring.version>4.2.6.RELEASE</spring.version>
    <!-- swagger  -->
    <swagger.version>2.6.1</swagger.version>
</properties>
<dependencies>
<!-- servlet Start -->
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>javax.servlet-api</artifactId>
			<version>${servlet_version}</version>
			<scope>provided</scope>
		</dependency>
		<!--END servlet END -->

		<!-- test start -->
		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>${junit_version}</version>
			<scope>test</scope>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-test</artifactId>
			<version>${spring.version}</version>
			<scope>test</scope>
		</dependency>
		<!-- end of test -->

		<!-- spring start -->
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-aop</artifactId>
			<version>${spring.version}</version>
		</dependency>

		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-aspects</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-beans</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-context</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-context-support</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-core</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-expression</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-jdbc</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-orm</artifactId>
			<version>${spring.version}</version>
		</dependency>

		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-tx</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-web</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-webmvc</artifactId>
			<version>${spring.version}</version>
		</dependency>
		<!-- spring end -->

		<!-- common start -->
		<dependency>
			<groupId>commons-configuration</groupId>
			<artifactId>commons-configuration</artifactId>
			<version>${commons_configuration}</version>
			<!-- <type>jar</type> <scope>compile</scope> -->
		</dependency>
		<!-- end of common -->


		<!-- jackson json   处理包-->
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>${jackson2.version}</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-core</artifactId>
			<version>${jackson2.version}</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-annotations</artifactId>
			<version>${jackson2.version}</version>
		</dependency>


		<!-- jackson json   处理包 END -->
		<!-- Log libs -->
		<dependency>
			<groupId>ch.qos.logback</groupId>
			<artifactId>logback-core</artifactId>
			<version>${logback.version}</version>
		</dependency>

		<dependency>
			<groupId>ch.qos.logback</groupId>
			<artifactId>logback-classic</artifactId>
			<version>${logback.version}</version>
		</dependency>
		<dependency>
			<groupId>ch.qos.logback</groupId>
			<artifactId>logback-access</artifactId>
			<version>${logback.version}</version>
		</dependency>

		<dependency>
			<groupId>org.codehaus.janino</groupId>
			<artifactId>janino</artifactId>
			<version>${log.janino.version}</version>
			<type>jar</type>
		</dependency>
		<dependency>
			<groupId>org.slf4j</groupId>
			<artifactId>slf4j-api</artifactId>
			<version>${slf4j_version}</version>
		</dependency>

		<dependency>
			<groupId>log4j</groupId>
			<artifactId>log4j</artifactId>
			<version>${log4j_version}</version>
		</dependency>
		<!-- end log -->
<!-- springfox START -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <!-- springfox END -->
        
        <!--petstore是官方的一个demo，加入此依赖是为了稍后参考接口描述的编写-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-petstore</artifactId>
            <version>${swagger.version}</version>
        </dependency>
		
		
		<!--解决tomcat部署跨域问题  -->  
    <dependency>  
        <groupId>com.thetransactioncompany</groupId>  
        <artifactId>cors-filter</artifactId>  
        <version>2.4</version>  
    </dependency>  
    <dependency>  
        <groupId>com.thetransactioncompany</groupId>  
        <artifactId>java-property-utils</artifactId>  
        <version>1.9.1</version>  
    </dependency>
</dependencies>
<!-- 配置编译插件和tomcat 环境 -->
<build>
		<finalName>las</finalName>
		<plugins>
			<!-- Force Java 7 -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.5.1</version>
				<configuration>
					<source>1.7</source>
					<target>1.7</target>
					<encoding>UTF-8</encoding>
				</configuration>
			</plugin>

			<plugin>
				<groupId>org.apache.tomcat.maven</groupId>
				<artifactId>tomcat7-maven-plugin</artifactId>
				<version>2.2</version>
				<configuration>
					<path>
						/${project.build.finalName}
					</path>
					<uriEncoding>UTF-8</uriEncoding>
					<port>9999</port>
				</configuration>
			</plugin>
		</plugins>
	</build>

1.2. SpringMvc配置文件spring-mvc.xml配置

<!--  注意component-scan 扫描路径 -->
<context:component-scan
		base-package="com.xxxx.las.web.control">
		<context:exclude-filter type="annotation"
			expression="org.springframework.stereotype.Service" />
</context:component-scan>
<!-- Scan springfox  demo -->
    <context:component-scan base-package="springfox.petstore.controller"/>

1.3. 添加springfox类

package com.xxxx.las.web.control.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;

import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Component
@EnableSwagger2
public class ApplicationSwaggerConfig {

    @Bean
    public Docket addUserDocket() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        ApiInfo apiInfo = new ApiInfo(
                "终端 API",
                "API Document管理",
                "V1.0.0",
                "www.xxxx.com",
                "759534585@qq.com",
                "",
                "");
        docket.apiInfo(apiInfo);
        return docket;
    }
}
//以上配置项目可以修改

1.4 web.xml 配置支持跨域请求

<!--解决tomcat部署跨域问题  -->  
        <filter>    
            <filter-name>CORS</filter-name>    
            <filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>    
            <init-param>    
             <param-name>cors.allowOrigin</param-name>    
                <param-value>*</param-value>    
            </init-param>    
            <init-param>    
             <param-name>cors.supportedMethods</param-name>    
                <param-value>GET, POST, HEAD, PUT, DELETE</param-value>    
            </init-param>    
            <init-param>    
             <param-name>cors.supportedHeaders</param-name>    
                <param-value>Accept, Origin, X-Requested-With, Content-Type, Last-Modified</param-value>    
            </init-param>    
            <init-param>    
                <param-name>cors.exposedHeaders</param-name>    
                <param-value>Set-Cookie</param-value>    
            </init-param>    
            <init-param>    
                <param-name>cors.supportsCredentials</param-name>    
                <param-value>true</param-value>    
            </init-param>    
        </filter>    
        <filter-mapping>    
            <filter-name>CORS</filter-name>    
            <url-pattern>/*</url-pattern>    
        </filter-mapping>

支持发布服务跨域请求的方式有多种、以上采用第三方已经提供好的解决方式。 注意：在线上环境请将以上配置去掉。

1.5. 一切搞定运行命令

mvn clean tomcat7:run 接口服务地址为：http://localhost:9999/las

springfox暴露的接口路径为：/v2/api-docs

接口已经暴露了。稍后介绍通过使用swagger-ui展示接口。

2. 前端环境搭建

2.1 下载swagger-ui源代码

下载路径：swagger-ui源代码

2.2 修改index.html 支持中文显示

行号：29 行

对比使用如下代码支持中文显示：

<!-- Some basic translations -->
  <script src='lang/translator.js' type='text/javascript'></script>
  <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
  <!-- <script src='lang/en.js' type='text/javascript'></script> -->
  <script src='lang/zh-cn.js' type='text/javascript'></script>

2.3 将swagger-ui打包放入tomcat中

效果图如下：

2.4 启动tomcat查看效果

红色框体输入框：输入你后台的接口地址路径 http://ip:port/{context}/v2/api-docs

2.5 配置后台接口服务

在swagger-ui首页输入框中输入以上启动的后台服务接口路径如下： http://localhost:9999/las/v2/api-docs 效果如下：

3.如何让后台接口暴露在swagger-ui下

可以通过springfox官网提供的实例代码学习： springfox-petstore 下一篇文章将详细介绍如何使用swagger-annotation让springmvc的接口直接暴露出来可以通过swagger-ui查看测试。

转载于:https://my.oschina.net/zzuqiang/blog/793463