關於api介面文檔RAP和swagger

標籤：swa   springmvc   adapter   doc   handler   app   margin   end   rip   

前言：

在之前的項目中用了將近一年的RAP,RAP是由阿里開源出來的，非常好用。github地址：https://github.com/thx/RAP。

當初在用此工具時，項目成員需要在介面文檔在所改動後，發郵件到項目群組成員，由於rap當時沒有此功能，所以還下載源碼，增加了發郵件功能。

將此功能代碼commit到了社區，好像社區沒有接納合入。 

後來使用了一年後，發現了swagger似乎使用很方便，直接跟代碼進行結合，需要重新使用其他工具進行配合了。

所以以下時對swagger的spring整合說明。

swagger整合spring說明：

如果是在springboot整合swagger是非常方便和簡單的，在網上一搜，或者到官網一看就明白了，這裡不在贅述。

以下主要是自己整合到springmvc的改造點：

1、pom.xm檔案，需要增加以下的依賴：

   版本為：

<jackson-version>2.5.0</jackson-version>

<swagger-springmvc-version>1.0.2</swagger-springmvc-version>

 

 增加的依賴為，：

<!-- 自動產生介面文檔工具 -->

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>${swagger-version}</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>${swagger-version}</version>

</dependency>

<!-- 自動產生介面文檔工具 -->

 

<!-- 整合swagger2需要用到 一般都用fastJson，但是swagger是用到jackson的--> 

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-annotations</artifactId>

<version>${jackson-version}</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-databind</artifactId>

<version>${jackson-version}</version>

</dependency>

<dependency>

<groupId>com.fasterxml.jackson.core</groupId>

<artifactId>jackson-core</artifactId>

<version>${jackson-version}</version>

</dependency>

<!-- 整合swagger2需要用到 -->

 

2.增加一個swagger的設定檔：

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.ComponentScan;

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;

 

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

 

/**

 * Swagger介面自動產生工具的配置

 * 

 * @author liuhangjun

 * @date 2017-01-22

 */

 

@Configuration

@EnableWebMvc

@EnableSwagger2

@ComponentScan("com.gradven.portalapi.controller")

public class SwaggerConfig extends WebMvcConfigurerAdapter {

 

@Bean

public Docket api() {

return new Docket(DocumentationType.SWAGGER_2).select()

.apis(RequestHandlerSelectors.basePackage("com.gradven.portalapi.controller")).build()

.apiInfo(apiInfo());

}

 

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

// 頁面標題

.title("api門戶 使用 Swagger2 構建RESTful API")

// 建立人

.contact(new Contact("gradven", null, "[email protected]"))

// 版本號碼

.version("1.0")

// 描述

.description("門戶介面").build();

}

 

 

@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/");

}

 

}

 

3.在spring的設定檔中將以上這個類進行注入：

<!-- swagger 配置 -->

<bean class="com.gradven.portalapi.commons.config.SwaggerConfig"/>

 

 

4.編寫controller，訪問swagger：

 

 只要在com.gradven.portalapi.controller這個包下，編寫controller，那麼再訪問http://localhost:port/swagger-ui.htm就可以看到介面了。

 

關於api介面文檔RAP和swagger