1. 好处
项目中使用swagger直接在线测试接口功能,不要要使用其他的测试工具,生成接口文档,简单明了。
2.集成swagger依赖组件
<!-- swagger集成 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 默认swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
3.pom.xml依赖组件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.md</groupId>
<artifactId>spring-boot2-parent</artifactId>
<version>0.0.1-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>spring-boot2-swagger</artifactId>
<packaging>jar</packaging>
<name>spring-boot2-swagger</name>
<description>Spring Boot, MVC, Rest API for App</description>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.version>1.8</java.version>
<swagger.version>2.9.2</swagger.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<!-- 构建成可运行的Web项目 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>net.sf.json-lib</groupId>
<artifactId>json-lib-ext-spring</artifactId>
</dependency>
<!-- swagger集成 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<!-- 默认swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
4. 新建Swagger配置类
package com.md.demo;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 创建一个Docket对象 调用select()方法, 生成ApiSelectorBuilder对象实例,该对象负责定义外漏的API入口
* 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate,在此我们使用any()方法,将所有API都通过Swagger进行文档管理
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()).select()
//如果不想将所有的接口都通过swagger管理的话,可以将RequestHandlerSelectors.any()修改为RequestHandlerSelectors.basePackage()
//.apis(RequestHandlerSelectors.any())
.apis(RequestHandlerSelectors.basePackage("com.md"))
.paths(PathSelectors.any())
.build();
}
@SuppressWarnings("deprecation")
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 标题
.title("SpringBoot2 中使用Swagger2 构建RESTful APIs")
// 简介
.description("This a demo for Swagger2")
// 服务条款
.termsOfServiceUrl("https://www.baidu.com")
// 作者个人信息
.contact("LAKERS")
// 版本
.version("1.0").build();
}
}
5. 编写接口swagger相关内容
package com.md.demo.rest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.md.demo.util.JsonResult;
import com.md.demo.util.ResultCode;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
/**
* @author Minbo
*/
@RestController
public class InitRest {
protected static Logger logger = LoggerFactory.getLogger(InitRest.class);
/**
* http://localhost:9090/hello
*
* @return
*/
@ApiOperation(value = "/hello 欢迎入口", httpMethod = "GET")
@RequestMapping(value = "/hello")
public String hello() {
logger.info("hello");
return "Hello greetings from spring-boot2-swagger";
}
@ApiOperation(value = "/getUserName 根据用户id获得用户的姓名", notes = "id不能为空", httpMethod = "GET")
@ApiImplicitParam(dataType = "string", name = "userId", value = "用户id", required = true)
@RequestMapping(value = "/getUserName")
public JsonResult getUserName(String userId) {
String result = "hello " + userId + ",name=张三";
return new JsonResult(ResultCode.SUCCESS, result);
}
/**
* Swagger注解用法:
*
* @Api:修饰整个类,描述Controller的作用
* @ApiOperation:描述一个类的一个方法,或者说一个接口
* @ApiParam:单个参数描述
* @ApiModel:用对象来接收参数
* @ApiProperty:用对象接收参数时,描述对象的一个字段
* @ApiResponse:HTTP响应其中1个描述
* @ApiResponses:HTTP响应整体描述
* @ApiIgnore:使用该注解忽略这个API
* @ApiError :发生错误返回的信息
* @ApiImplicitParam:一个请求参数
* @ApiImplicitParams:多个请求参数
*/
}
6. 启动项目,访问:http://localhost:9090/swagger-ui.html
![3f51c1a3c2d8fe06397c0bd977594af6.png](https://i-blog.csdnimg.cn/blog_migrate/3d212003143c356923ad65101e6332ef.jpeg)
点击接口,输入参数,执行就可以测试接口功能。