Spring boot 多模块项目 + Swagger 让你的API可视化
Spring boot 多模块项目 + Swagger 让你的API可视化
前言
手写 Api 文档的几个痛点：
- 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
- 接口返回结果不明确
- 不能直接在线测试接口，通常需要使用工具，比如postman
- 接口文档太多，不好管理
为了前后台更好的对接，为了以后交接方便，为了不再长篇大论的手写 api 文档，那么就来用Swagger吧(不是打广告，确实强)，它可以轻松的整合到 Spring 中，它既可以减少我们手写 api 文档的时间，同时又将说明文档整合到我们的代码中，这样前台看着也方便,后台工作也舒坦。
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单(其他好处网上自己搜在这里就不再多说了)。
官网地址： https://swagger.io/
本篇内容：
（1）构建多模块项目（可选单模块步骤）
（2）pom.xml 配置加载依赖
（3）Swagger 配置类（Bean）
（4）启动类配置
（5）创建工具类
（6）User 实例类
（7）定义 restful 接口（Controller 层）
为帮助快速入门上手使用，提供了简单的增删改查，使用的参数配置示例
本篇测试环境：
- SpringBoot 2.0.5.RELEASE
- Swagger 2.9.2
- JDK 1.8.191
成功截图：
第一步：构建多模块项目（可选步骤）
如果想使用多模块，请先构建项目（建议）：
如果不想使用多模块（下面模块请根据自己项目修改）
所有涉及到的文件结构：
第二步：pom.xml 配置加载依赖
Spring boot 项目都会有一些依赖，为了更直观，只贴必要的部分
为你的 Spring Boot 项目再增加下面两个依赖：
pom.xml 配置：
<!--可以去下面地址查看最近版本-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>第三步：Swagger 配置类（Bean）
注意：
- basePackage 是需要自己配置的，换成自己需要扫描的包，会扫描其所有子包
- 一个就配主模块，多个就配大包，或分开配
用 @Configuration 注解该类，等价于XML中配置beans；
用 @Bean 标注方法等价于XML中配置bean
不是不可以使用 xml，提倡使用注解，是不是想起点什么？
SwaggerConfig.java 源代码：
package com.xpwi.main.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* 描述：Swagger2 Config Bean
*
* @author Xiao Pengwei
* @since 2019-03-27
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xpwi"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot使用Swagger构建api文档")
.description("简单优雅的 restfun 风格 https://icode.blog.csdn.net")
.termsOfServiceUrl("https://icode.blog.csdn.net")
.version("1.0")
.build();
}
}第四步：启动类配置
Application.class 加上注解 @EnableSwagger2 表示开启Swagger
package com.xpwi.main;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.Date;
/**
* 描述：Spring Boot 多模块测试项目
* @author Xiao Pengwei
* @since 2019-03-25
*/
@EnableSwagger2
@SpringBootApplication
@RestController
//扫描 main,test 模块中的下的所有包
//在 pom 加载子模块依赖才可以扫包
@ComponentScan({"com.xpwi.main","com.xpwi.test","com.xpwi.login"})
public class App {
public static void main(String[] args) {
//启动 Web 容器
SpringApplication.run(App.class, args);
System.out.println("[启动成功]"+new Date());
}
}第五步：创建工具类
用于返回通用数据格式的工具类
CommonResult.java 源代码：
package com.xpwi.main.util;
/**
* 描述：通用返回类型
* @author Xiao Pengwei
* @since 2019-03-27
*/
public class CommonResult {
private String status;
private Object result;
private Object message;
public String getStatus() {
return status;
}
public void setStatus(String status) {
this.status = status;
}
public Object getResult() {
return result;
}
public void setResult(Object result) {
this.result = result;
}
public Object getMessage() {
return message;
}
public void setMessage(Object message) {
this.message = message;
}
}
第六步：User 实例类
User 模拟对应数据库字段的实体类
User.java 源代码：
package com.xpwi.main.entity;
import java.util.Date;
/**
* 描述：User 实体类
* @author Xiao Pengwei
* @since 2019-03-27
*/
public class User {
private String id;
private String username;
private int age;
private Date ctm;
public String getId() {
return id;
}
public void setId(String id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
public Date getCtm() {
return ctm;
}
public void setCtm(Date ctm) {
this.ctm = ctm;
}
}
第七步：！定义 restful 接口（Controller 层）
最重要的一步，也是开发中最常用的一步
创建 UserController.java 源代码：
package com.xpwi.main.controller;
import com.xpwi.main.entity.User;
import com.xpwi.main.util.CommonResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* 描述：Controller 类
* @author Xiao Pengwei
* @since 2019-03-27
*/
@RestController
@Api(value = "用户测试模块")
public class UserController {
// 创建线程安全的Map
static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());
/**
* 根据ID查询用户
* @param id
* @return
*/
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
public ResponseEntity<CommonResult> getUserById (@PathVariable(value = "id") String id){
CommonResult commonResult = new CommonResult();
try {
User user = users.get(id);
commonResult.setResult(user);
commonResult.setStatus("ok");
} catch (Exception e) {
commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
commonResult.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(commonResult);
}
/**
* 查询用户列表
* @return
*/
@ApiOperation(value="获取用户列表", notes="获取用户列表")
@RequestMapping(value = "users", method = RequestMethod.GET)
public ResponseEntity<CommonResult> getUserList (){
CommonResult commonResult = new CommonResult();
try {
List<User> userList = new ArrayList<User>(users.values());
commonResult.setResult(userList);
commonResult.setStatus("ok");
} catch (Exception e) {
commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
commonResult.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(commonResult);
}
/**
* 添加用户
* @param user
* @return
*/
@ApiOperation(value="创建用户", notes="根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value = "user", method = RequestMethod.POST)
public ResponseEntity<CommonResult> add (@RequestBody User user){
CommonResult commonResult = new CommonResult();
try {
users.put(user.getId(), user);
commonResult.setResult(user.getId());
commonResult.setStatus("ok");
} catch (Exception e) {
commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
commonResult.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(commonResult);
}
/**
* 根据id删除用户
* @param id
* @return
*/
@ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
public ResponseEntity<CommonResult> delete (@PathVariable(value = "id") String id){
CommonResult commonResult = new CommonResult();
try {
users.remove(id);
commonResult.setResult(id);
commonResult.setStatus("ok");
} catch (Exception e) {
commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
commonResult.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(commonResult);
}
/**
* 根据id修改用户信息
* @param user
* @return
*/
@ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String",paramType = "path"),
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
})
@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
public ResponseEntity<CommonResult> update (@PathVariable("id") String id, @RequestBody User user){
CommonResult commonResult = new CommonResult();
try {
User user1 = users.get(id);
user1.setUsername(user.getUsername());
user1.setAge(user.getAge());
users.put(id, user1);
commonResult.setResult(user1);
commonResult.setStatus("ok");
} catch (Exception e) {
commonResult.setResult(e.getClass().getName() + ":" + e.getMessage());
commonResult.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(commonResult);
}
@ApiIgnore//使用该注解忽略这个API
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}第八步：启动 Spring Boot，打开浏览器
只需访问：
http://localhost:8080/swagger-ui.htmlswagger-ui.html 是默认的，不用担心自己没有创建这个文件，这个就是那个 UI 咯
第九步：常用注解
swagger 提供的常用的注解有：
- @Api：用在类上，说明该类的作用
- @ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value 和 notes 的作用差不多，都是对请求进行说明；tags 则是对请求进行分类的，比如你有好几个 controller，分别属于不同的功能模块，那这里我们就可以使用 tags 来区分了。
- @ApiImplicitParams：用在方法上包含一组参数说明
- @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的各个方面。
- @ApiResponses：用于表示一组响应
- @ApiResponse：用在 @ApiResponses 中，一般用于表达一个错误的响应信息
- @ApiModel：描述一个 Model 的信息（这种一般用在post创建的时候，使用
@RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候）表明这是一个被 swagger 框架管理的 model，用于class上 - @ApiModelProperty： 这里顾名思义，描述一个 model 的属性，就是标注在被标注了 @ApiModel 的class的属性上，这里的 value 是对字段的描述，example 是取值例子，注意这里的 example很有用，对于前后端开发工程师理解文档起到了关键的作用，因为会在 api 文档页面上显示出这些取值来；这个注解还有一些字段取值，可以自己研究，举例说一个：position，表明字段在 model 中的顺序。
第十步：使用
一般 swagger 需要一下api的权限，需要在对应的模块进行排除：
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-ui.html
http://localhost:8080/swagger-resources/configuration/security
如果项目上线并且需要关闭 swagger 接口，可以通过配置权限，或者再 SwaggerConfig 里面
return new Docket 的时候加多一个.enable(false)
技术朋友群
- 一键加群
- QQ群：621657432
版权声明：本文为xpwi原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。