1、添加 Swagger 与 SpringMVC 的依赖
<dependency>
<groupId>com.mangofactory</groupId>
<artifactId>swagger-springmvc</artifactId>
<version>1.0.2</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</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-annotations</artifactId>
<version>${jackson.version}</version>
</dependency>
以上是必须加的依赖,下面的依赖参考加入
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.7</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.7</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>19.0</version>
</dependency>
<dependency>
<groupId>com.fasterxml</groupId>
<artifactId>classmate</artifactId>
<version>1.3.1</version>
</dependency>
2、编写 Swagger 与 SpringMVC 整合的配置类
package com.english17.config;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Created by Liwei on 2016/2/14.
*/
@Configuration
@EnableSwagger
public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}
/**
* 自定义实现 customImplementation
* @return
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation(){
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*?");
}
/**
* title;
description;
terms of serviceUrl;
contact email;
license type;
license url;
* @return
*/
private ApiInfo apiInfo(){
ApiInfo apiInfo = new ApiInfo(
"标题 title",
"描述 description",
"termsOfServiceUrl",
"联系邮箱 contact email",
"许可证的类型 license type",
"许可证的链接 license url"
);
return apiInfo;
}
}
3、修改配置文件
(1)在 SpringMVC 的配置文件中添加和修改:
在 SpringMVC 的扫描注解里面加上扫描注解 @Configuration
<context:include-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/>
这是因为,我们下面的两个 bean 都被 @Configuration
注解
<bean class="com.english17.config.SwaggerConfig"></bean>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig"></bean>
对称地,要在 Spring 的配置文件中减去对 @Configuration
的扫描
<context:exclude-filter type="annotation" expression="org.springframework.context.annotation.Configuration"/>
4、下载 UI,复制到 SpringMVC 的静态文件的目录
启动服务,输入下面的链接(主机名和端口号要用你自己的)
http://localhost:8888/api-docs
要看到返回一个 json。
http://localhost:8888/resources/swagger/index.html
开发中使用频率比较高的注解:
1、@ApiModel
:标注在类上
2、@ApiModelProperty
:标注在属性上
3、@ApiOperation
:标注在方法上
4、@ApiParam
:标注在方法参数上
5、@Api
:标注在控制器上
具体的使用方法可以直接看源代码。