玩转Spring Boot2.x 之 整合丝袜哥(swagger)篇

原文：https://zhuoqianmingyue.blog.csdn.net/article/details/82749274

作者： 桌前明月

作为一个后端开放者，当你开发完API接口后为写文档而烦恼吗？当app开发人员或前端开发人员看不懂的你写的接口文档，你还得去给他们讲一遍怎么使用而烦恼吗？使用我介绍的swagger 这些烦恼统统的消失。swagger 一个集预览和测试于一身的在线可视化 RESTful 风格的 Web 服务框架。

好啦，我们不扯蛋直接切入正题体，在 SpringBoot 中使用 swagger 第一个步骤是先引入 swagger 的依赖到pom 文件中。

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.7.0</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.7.0</version>
</dependency>

编写API 服务：一个用户的增删改查。

package cn.lijunkui.springbootlearn.swagger;
@Data 
public class User {
 private String name;
 private Integer age;
}

UserController :

package cn.lijunkui.springbootlearn.swagger;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;
@RestController()
@RequestMapping("/user")
public class UserController {
 Logger log = LoggerFactory.getLogger(UserController.class);
 /**
 * 根据用户id 查询用户
 * @return
 */
 @GetMapping("/{id}")
 public User get(@PathVariable(name = "id") Long id){
 User user = new User();
 user.setName("lijunkui");
 user.setAge(18);
 log.info("springboot查询用户成功："+"id:{}",id);
 return user;
 }
 /**
 * 添加用户
 */
 @PostMapping()
 public void add(User user){
 log.info("springboot添加用户成功："+"name:{},age:{}",user.getName(),user.getAge());
 }
 /**
 * 全部更新
 * @param user
 */
 @PutMapping()
 public void updatePut(User user){
 log.info("springboot Put 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
 }
 /**
 * 局部更新
 */
 public void updatePatch(@PathVariable("name") String name){
 log.info("springboot Patch 修改用户成功："+"name:{}",name);
 }
 /**
 * 删除用户
 */
 @DeleteMapping("/{id}")
 public void delete(@PathVariable("id") Long id){
 User user = new User();
 user.setName("lijunkui");
 user.setAge(18);
 log.info("springboot 删除用户成功："+"id:{}",id);
 }
 /**
 * 根据requestBody 更新用户信息
 * @param user
 * @return
 */
 @PostMapping("/updateUserByRequestBody")
 public void updateUserByRequestBody(@RequestBody User user){
 log.info("updateUserByRequestBody 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
 }
}

编写swagger Config 使用 swagger ：

package cn.lijunkui.springbootlearn.swagger;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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;
//让Spring来加载该类配置
@Configuration
//是否禁用swagger 的配置
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
//启用Swagger2
@EnableSwagger2
public class SwaggerConfig {
 @Bean
 public Docket alipayApi() {
 return new Docket(DocumentationType.SWAGGER_2)
 .groupName("简单用户管理API接口文档")
 .apiInfo(apiInfo())
 .select()
 .apis(RequestHandlerSelectors.basePackage("com.ljk.springBootLearn.users"))
 .paths(PathSelectors.any()).build();
 }
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
 .title("SprignBoot学习专栏")
 .description("集成swagger")
 .termsOfServiceUrl("https://blog.csdn.net/ljk126wy")
 //创建人
 .contact(new Contact("桌前明月", "http://www.baidu.com", ""))
 //版本
 .version("1.0")
 //API 描述
 .description("简单介绍如有问题还望指正")//
 .build();
 }
}

application.yml 配置内容：

server:
 port: 8080 #浏览器访问项目端口号
 servlet:
 context-path: /springootLearn #浏览器访问项目的名称
swagger:
 enable: true

添加用户

我们可以添加用户进行测试

我们这里就不一个个进行测试啦。

接下来 我们开始对每个接口进行接口描述介绍：

package cn.lijunkui.springbootlearn.swagger;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;
@Api(tags ="用户管理")
@RestController()
@RequestMapping("/user")
public class UserController {
 Logger log = LoggerFactory.getLogger(UserController.class);
 /**
 * 根据用户id 查询用户
 * @return
 */
 @ApiOperation(value="根据id获取用户信息")
 @ApiImplicitParam(paramType= "path", name = "id", value = "用户id", required = true, dataType = "Long")
 @GetMapping("/{id}")
 @ApiResponses({ @ApiResponse(code = 400, message = "请求无效 (Bad request)") })
 public User get(@PathVariable(name = "id") Long id){
 User user = new User();
 user.setName("lijunkui");
 user.setAge(18);
 log.info("springboot查询用户成功："+"id:{}",id);
 return user;
 }
 /**
 * 添加用户
 */
 @ApiOperation(value="添加用户")
 @ApiImplicitParams({
 @ApiImplicitParam(name="name",value="用户名",dataType="string", required = true, paramType = "form",example="ljk"),
 @ApiImplicitParam(name="age",value="用户年龄",dataType="int", paramType = "form")})
 @PostMapping()
 public void add(User user){
 log.info("springboot添加用户成功："+"name:{},age:{}",user.getName(),user.getAge());
 }
 /**
 * 全部更新
 * @param user
 */
 @PutMapping()
 public void updatePut(User user){
 log.info("springboot Put 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
 }
 /**
 * 局部更新
 */
 public void updatePatch(@PathVariable("name") String name){
 log.info("springboot Patch 修改用户成功："+"name:{}",name);
 }
 /**
 * 删除用户
 */
 @DeleteMapping("/{id}")
 public void delete(@PathVariable("id") Long id){
 User user = new User();
 user.setName("lijunkui");
 user.setAge(18);
 log.info("springboot 删除用户成功："+"id:{}",id);
 }
 /**
 * 根据requestBody 更新用户信息
 * @param user
 * @return
 */
 @PostMapping("/updateUserByRequestBody")
 public void updateUserByRequestBody(@RequestBody User user){
 log.info("updateUserByRequestBody 修改用户成功："+"name:{},age:{}",user.getName(),user.getAge());
 }
}

@Api ：说明接口类的作用。

@ApiOperation 用在方法上 说明方法的作用
@ApiImplicitParam 方法中参数的说明
 paramType
 head 请求参数获取 @RequestHeader
 query 请求参数获取 @RequestParam
 path 请求参数获取 @PathVariable
 body
 form
 name 参数名
 value 参数的意思
 required 参数是否必传
 dataType 参数类型
 defaultValue 默认值

@ApiImplicitParams：添加多个方法中参数的说明 包含 @ApiImplicitParam ：

@ApiModel:描述model信息

@ApiModelProperty:描述model属性的信息

@ApiModel(value="user对象",description="用户对象user")
@Data
public class User {
 @ApiModelProperty(value="用户名",name="name",example="xingguo")
 private String name;
 @ApiModelProperty(value="年龄1",name="age",required=true)
 private Integer age;
}

@ApiResponses @ApiResponse 错误相应信息描述：

参考文献：https://yq.aliyun.com/articles/181435
源码地址：https://github.com/zhuoqianmingyue/springbootexamples