关于api接口文档RAP和swagger

Posted Gradven

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了关于api接口文档RAP和swagger相关的知识,希望对你有一定的参考价值。

前言:

在之前的项目中用了将近一年的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的主要内容,如果未能解决你的问题,请参考以下文章

API接口文档利器:Swagger

Swagger UI教程 API 文档神器 搭配Node使用 web api 接口文档 mvc接口文档

MVC WebApi Swagger帮助文档 接口用法

使用swagger实现web api在线接口文档

Swagger---API 接口文档自动生成工具

Spring Cloud Zuul中使用Swagger汇总API接口文档