前言
相信大部分的开发人员都或多或少地被接口文档折磨过。后端人员接口开发完成，又需编写及维护接口文档会耗费不少精力，经常来不及更新。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 里面可以其他更多的信息。
其中主要属性有：
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：参数的默认值
复制代码
code：数字，例如200 请求成功 message：信息，例如"请求成功" response：请求成功返回的数据信息
复制代码
源码
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
# mysqlspring.datasource.url=jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&characterEncoding=utf-8&zeroDateTimeBehavior=convertToNullspring.datasource.username=testspring.datasource.password=123456spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driverspring.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@EnableSwagger2public 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")@Controllerpublic 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 相关信息，相信一定会有新大陆发现的。
好了，感谢您的阅读，希望您喜欢，如对您有帮助，欢迎点赞收藏。如有不足之处，欢迎评论指正。下次见。
评论