13.玩转Spring Boot 集成swagger2

时间：2022-08-01 23:19:56

玩转Spring Boot 集成swagger


       在使用Spring Boot 开发Restful API，你是否在为写接口文档而郁闷呢？那么swagger一定适合你。使用swagger你可以有份很强大的Restful API文档。使用Spring Boot与Swagger集成我只能用非常简单来形容，接下来就具体说说。


1.pom.xml加入依赖

      创建工程后，打开pom.xml加入以下依赖： 
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>

2.创建入口启动类

      创建入口启动类，代码如下： 
package com.chengli.springboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

import com.google.common.base.Predicate;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import static com.google.common.base.Predicates.*;

@SpringBootApplication
@EnableSwagger2 //启用swagger
public class MainConfig {
public static void main(String[] args) {
SpringApplication.run(MainConfig.class, args);
}

/**
 * 这里是可以分组定义多个Docket，我这里举例定义了两个，一个是业务文档类型，一个是财务文档类型。
 * 定义了多个分组后，在页面上提供了一个下拉来选择组，具体运行起来看看就知道了。
 * 我这个是参照官方的代码改了改，有的删了，具体的大家看官方文档吧，
 * 地址：http://springfox.github.io/springfox/docs/current/#plugins-available-for-extensibility
 * 
 */

/**业务文档*/
@Bean
public Docket businessDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("业务文档") //分组名称
.select()
.paths(businessPaths()) //指定路径处理PathSelectors.any()代表所有的
.build()
.apiInfo(apiInfo());
}
@SuppressWarnings("unchecked")
private Predicate<String> businessPaths() {
return or(PathSelectors.regex("/user.*"));//这里是正则表达式
}


/**财务文档*/
@Bean
public Docket financeDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("财务文档")//分组名称
.select()
.paths(financePaths())//指定路径处理PathSelectors.any()代表所有的
.build()
.apiInfo(apiInfo());
}
@SuppressWarnings("unchecked")
private Predicate<String> financePaths() {
return or(PathSelectors.regex("/finance.*"));//这里是正则表达式
}


/**指定了页面显示的信息，标题、描述*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("使用Spring Boot 集成 swagger")
.description("玩转Spring Boot 博客地址：http://blog.csdn.net/cl_andywin").build();
}

}

3.创建Controller

      （1）创建用户实体

package com.chengli.springboot.swagger.pojo;

public class User {
private Long id;
private String name;
private String sex;
private Integer age;

public Long getId() {
return id;
}

public void setId(Long id) {
this.id = id;
}

public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

public String getSex() {
return sex;
}

public void setSex(String sex) {
this.sex = sex;
}

public Integer getAge() {
return age;
}

public void setAge(Integer age) {
this.age = age;
}

@Override
public String toString() {
return "User [id=" + id + ", name=" + name + ", sex=" + sex + ", age=" + age + "]";
}

}

   

   （2）创建controller代码如下

 
package com.chengli.springboot.swagger.controller;

import java.util.List;

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 com.chengli.springboot.swagger.pojo.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/user")
@Api(tags = "user")
public class UserController {
public List<User> getUserList() {
return null;
}

/*
 * 这里就写两个例子啊，其余的都一样了，就不在写了。
 * 
 */

/**
 * 增加的时候，我通过用参数的方式来增加
 * 
 * @param user
 * @return
 */
@ApiOperation("增加用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "name", dataType = "String", required = true, value = "姓名", defaultValue = "成立"),
@ApiImplicitParam(paramType = "query", name = "sex", dataType = "String", required = true, value = "性别", defaultValue = "男"),
@ApiImplicitParam(paramType = "query", name = "age", dataType = "int", required = false, value = "年龄", defaultValue = "18") })
@RequestMapping(method = RequestMethod.POST)
public User save(User user) {
// 这里为了方便直接将输入内容返回
return user;
}

/**
 * 修改的时候，我通过使用JSON的方式来修改
 * 
 * @param id
 * @param user
 * @return
 */
@ApiOperation(value = "修改用户信息", notes = "根据ID修改用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "path", name = "id", value = "用户ID", required = true, dataType = "Long"),
@ApiImplicitParam(paramType = "body", name = "user", value = "用户实体", required = true, dataType = "User") })
@RequestMapping(value = "/{id}", method = RequestMethod.PUT)
public User update(@PathVariable Long id, @RequestBody User user) {
// 这里为了方便直接将输入内容返回
return user;
}
}

到这里就已经配置好了，启动试试吧，在浏览器上输入：http://localhost:8080/swagger-ui.html，显示界面如下： 13.玩转Spring Boot 集成swagger2

4.常用注解介绍

@Api 表示该类是swagger资源，也就会处理成API
@ApiImplicitParam 请求参数
@ApiImplicitParams 请求参数集合，用于包装请求参数
@ApiModel 在使用对象的时候
@ApiModelProperty model属性
@ApiOperation 方法描述
@ApiParam 额外的元数据操作参数
@ApiResponse 出现错误的响应信息
@ApiResponses 出现错误的响应信息集合，用于包装出现错误的响应信息
@Authorization 授权对资源使用或操作
@AuthorizationScope Oauth2授权范围


具体的注解看官网，其余的就不叙述了。完整示例代码在QQ交流群中：springboot-swagger.zip

有兴趣的朋友可以加群探讨相互学习：
Spring Boot QQ交流群：599546061
标签：

相关文章