Springfox與SpringMvc集成實現接口文檔化

時間  2019-11-11
標籤 springfox springmvc 集成 實現 接口 文檔 欄目 Spring 简体版
原文   原文鏈接

準備環境

  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>

支持發佈服務跨域請求的方式有多種、以上採用第三方已經提供好的解決方式。 注意：在線上環境請將以上配置去掉。javascript

1.5. 一切搞定運行命令

mvn clean tomcat7:run 接口服務地址爲：http://localhost:9999/lashtml

springfox暴露的接口路徑爲：/v2/api-docs前端

接口已經暴露了。稍後介紹經過使用swagger-ui展現接口。java

2. 前端環境搭建

2.1 下載swagger-ui源代碼

下載路徑：swagger-ui源代碼nginx

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

行號：29 行git

對比使用以下代碼支持中文顯示：github

<!-- 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中

效果圖以下： 輸入圖片說明web

2.4 啓動tomcat查看效果

輸入圖片說明 紅色框體輸入框：輸入你後臺的接口地址路徑 http://ip:port/{context}/v2/api-docsspring

2.5 配置後臺接口服務

在swagger-ui首頁輸入框中輸入以上啓動的後臺服務接口路徑以下： http://localhost:9999/las/v2/api-docs 效果以下： 輸入圖片說明express

3.如何讓後臺接口暴露在swagger-ui下

能夠經過springfox官網提供的實例代碼學習： springfox-petstore 下一篇文章將詳細介紹如何使用swagger-annotation讓springmvc的接口直接暴露出來能夠經過swagger-ui查看測試。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程