前言
相信大部分的开发人员都或多或少地被接口文档折磨过。后端人员接口开发完成，又需编写及维护接口文档会耗费不少精力，经常来不及更新。Swagger基于注解进行开发，提供了一个灵活的接口文档模板。更新运行编译后，直接可以在线预览，避免了重复修改的问题，下面开始介绍Swagger UI。
什么是Swagger UI
Swagger UI是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。主要作用是：接口的文档在线自动生成和在线预览，可以进行业务功能的测试。
目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。
Swagger UI的使用
引入依赖
Maven方式引入所需要的依赖包，具体信息如下：
<!-- swagger start --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.5.0</version> </dependency> <!-- swagger end -->
Swagger UI 配置类
Swagger UI 配置类首先是提供了一个强大的构造器，用于创建API。其中构建API的基本信息有页面的标题、版本号、接口文档的描述、服务条款的地址、contact、许可信息、许可信息地址等，其中contact里面可以其他更多的信息。
- ApiInfo：构建Api文档的详细信息函数。
- Docket:Swagger UI返回的API文档信息。
其中主要属性有：
- apiInfo()是apiInfo的基本信息。
- select()Api 选择器生成器。
- apis为当前请求处理程序选择器所需要进行API文档的包路径。
- paths路径选择器为any任何包都处理。
public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //为当前包路径 .apis(RequestHandlerSelectors.basePackage("com.example.demo")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot 使用 Swagger2 构建RESTful API") .contact(new Contact("Bryan", "http://blog.bianxh.top/", "")) .version("1.0") .description("API 描述") .build(); }
Swagger UI 注解
- @Api：用在类上，说明该类的作用。
- @ApiOperation：注解来给API增加方法说明。
- @ApiImplicitParams : 用在方法上包含一组参数说明。
- @ApiImplicitParam：用来注解来给方法入参增加说明。
常用的参数：
paramType：指定参数放在哪个地方 header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用） name：参数名 dataType：参数类型 required：参数是否必须传(true | false) value：说明参数的意思 defaultValue：参数的默认值
- @ApiResponses：用于表示一组响应
- @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。 其中ApiResponse包含三个属性
code：数字，例如200 请求成功 message：信息，例如"请求成功" response：请求成功返回的数据信息
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
源码
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 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.3.0.RELEASE</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.example</groupId> <artifactId>swagger</artifactId> <version>0.0.1-SNAPSHOT</version> <name>swagger</name> <description>Demo project for Spring Boot and MyBatis and Swagger</description> <properties> <java.version>1.8</java.version> </properties> <dependencies> <!-- commons start --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.7</version> </dependency> <!-- commons end --> <!-- mybatis start--> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <!-- mybatis-spring-boot-starter --> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>2.1.1</version> </dependency> <!-- druid --> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid</artifactId> <version>1.1.11</version> </dependency> <!-- mybatis end--> <!--junit start --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> <exclusions> <exclusion> <groupId>org.junit.vintage</groupId> <artifactId>junit-vintage-engine</artifactId> </exclusion> </exclusions> </dependency> <!-- junjit --> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>4.12</version> <scope>test</scope> </dependency> <!--junit end --> <!-- swagger start --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.5.0</version> </dependency> <!-- swagger end --> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
application.properties
server.port=8888 # mysql spring.datasource.url=jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNull spring.datasource.username=test spring.datasource.password=123456 spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver spring.datasource.type=com.alibaba.druid.pool.DruidDataSource mybatis.mapper-locations=classpath*:mapper/**/*.xml
SwaggerConfig
package com.example.demo.config; 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.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @ClassName SwaggerConfig * @Description: SwaggerConfig配置 * @Author JavaZhan @公众号:Java全栈架构师 * @Date 2020/6/13 * @Version V1.0 **/ @Configuration @EnableSwagger2 public class SwaggerConfig { /** * @ClassName 创建Docket * @Description: 创建Docket * @Author JavaZhan @公众号:Java全栈架构师 * @Date 2020/6/13 * @Version V1.0 **/ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo")) .paths(PathSelectors.any()) .build(); } /** * @ClassName ApiInfo * @Description: ApiInfo * @Author JavaZhan @公众号:Java全栈架构师 * @Date 2020/6/13 * @Version V1.0 **/ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("掘金作者 小阿杰") .contact(new Contact("小阿杰","https://juejin.cn/user/2040300414187416/posts", "")) .version("1.0") .description("公众号: Java全栈架构师 API 描述") .build(); } }
DemoSwaggerApplication
package com.example.demo; import org.mybatis.spring.annotation.MapperScan; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; /** * @ClassName Swagger UI集成测试 * @Description: Swagger UI集成测试启动类 * @Author JavaZhan @公众号:Java全栈架构师 * @Date 2020/6/13 * @Version V1.0 **/ @SpringBootApplication @MapperScan("com.example.demo.mapper") public class DemoSwaggerApplication { public static void main(String[] args) { SpringApplication.run(DemoSwaggerApplication.class, args); } } 复制代码
UserController
package com.example.demo.controller; import com.example.demo.module.User; import com.example.demo.service.UserService; import io.swagger.annotations.Api; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiOperation; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.ResponseBody; import javax.annotation.Resource; import java.util.List; /** * @ClassName UserController * @Description: 用户管理 * @Author JavaZhan @公众号:Java全栈架构师 * @Date 2020/6/13 * @Version V1.0 **/ @Api(description = "用户管理") @RequestMapping("user") @Controller public class UserController { @Resource private UserService userService; @ApiOperation(value = "获取所有用户") @RequestMapping(value = "getAllUser",method = RequestMethod.GET) @ResponseBody public List<User> getAllUser(){ return userService.getAllUser(); } }
使用Swagger UI
打开API
在浏览器输入：http://localhost:8888/swagger-ui.html出现如下图中接口文档信息，即Swagger文档集成成功：
测试接口
选择user/getAllUser这个接口，获取所有用户信息， 可以看到请求方式是GET请求。请求参数为空，返回的Model是User，
点击Try it out 。接口自动请求，返回请求参数和返回的值信息。请求成功，返回状态为200。返回正常的List数据信息。
结语
这样Swagger与Spring Boot集成成功啦。更多的测试大家可以深入研究一下Swagger相关信息，相信一定会有新大陆发现的。
