Spring Boot集成Swagger 2实现API接口管理

1. 引言
   随着微服务架构体系的发展和应用， 为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。

传统的API文档编写存在以下几个痛点：

对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
API接口返回信息不明确
缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
接口文档太多，不便于管理
为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

Swagger具有以下优点：

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。
当然也不能说Swagger就一定是完美的，它也有缺点，最明显的就是代码移入性比较强。

2. Swagger 2.0 集成配置
3. 添加Swagger2的Maven依赖

... 项目其他依赖包 ... io.springfox springfox-swagger2 2.7.0 io.springfox springfox-swagger-ui 2.7.0

2. 创建Swagger2配置文件
   package com.gayond.hurricane.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;

import java.util.ArrayList;
import java.util.List;

@Configuration
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.garyond.hurricane.rest")) // 配置需要扫描的包路径
            .paths(PathSelectors.any())
            .build();
            //.globalOperationParameters(pars);
}

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("身份认证服务")
            .description("提供统一的身份认证与身份验证服务")
            .termsOfServiceUrl("http://www.baidu.com")
            .version("0.0.1")
            .build();
}

}

说明：

• 用 @Configuration 注解该类，等价于在Spring XML配置文件中beans配置；
• 用 @Bean 标注方法等价于Srping XML配置文件中的bean配置。

3. Spring Boot主应用中启用Swagger配置

需要在Spring Boot主应用中添加 @EnableSwagger2 注解说明启用Swagger服务

package com.garyond.hurricane.myservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class JwtServiceApplication {

public static void main(String[] args) {
    SpringApplication.run(JwtServiceApplication.class, args);
}

}

3. Restful接口定义与展示
4. 在Spring Controller中使用Swagger注解

package com.garyond.hurricane.rest;

import com.garyond.hurricane.myservice.annotation.RequiredPerms;
import com.garyond.hurricane.myservice.controller.BaseController;
import com.garyond.hurricane.myservice.entity.JsonResult;
import com.garyond.hurricane.myservice.model.User;
import com.garyond.hurricane.myservice.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**

• 用户操作Restful接口

• @author Garyond

• @version 1.0
  */
  @RestController
  @Api(value = “/v1/user”, description = “用户CRUD操作接口”)
  @RequestMapping("/v1/user")
  public class UserRestController extends BaseController{

  @Autowired
  private UserService userService;

  /**

  • 检索用户信息

  • @return
    */
    @RequestMapping(value = “/query”, method = {RequestMethod.GET})
    @RequiredPerms(“user:list”)
    @ApiOperation(value=“根据用户名查询用户信息”, notes=“根据用户名查询用户信息”)
    public @ResponseBody JsonResult queryUsers(@ApiParam(name=“username”, value = “用户名”, required = true) @RequestParam(“username”) String username) {

    if (null == username || StringUtils.isBlank(username)) {
    return this.renderError(“用户名不能为空”);
    }

    User user = userService.getUserByUsername(username);

    if (null != user) {
    return this.renderSuccess(user);
    } else {
    return this.renderError(“无用户数据”);
    }
    }

  /**

  • 获取所有用户信息

  • @return
    */
    @RequestMapping(method = {RequestMethod.GET})
    @RequiredPerms(“user:list”)
    @ApiOperation(value=“获取用户列表”, notes=“获取用户列表”)
    public @ResponseBody JsonResult listUsers() {

    List userList = userService.findAll();

    if (null != userList && userList.size() > 0) {
    return this.renderSuccess(userList);
    } else {
    return this.renderError(“无用户数据”);
    }
    }

  /**

  • 获取用户信息

  • @param userId

  • @return
    */
    @RequestMapping(value = “/{userId}”,method = {RequestMethod.GET})
    @RequiredPerms(“user:list”)
    @ApiOperation(value=“根据UserId获取用户信息”, notes=“根据UserId获取用户信息”)
    @ApiImplicitParam(name = “userId”, value = “用户ID”, required = true, dataType = “String”, paramType = “path”)
    public @ResponseBody JsonResult getUser(@PathVariable(“userId”) String userId) {
    User user = userService.getUserById(userId);

    if (null != user) {
    return this.renderSuccess(user);
    } else {
    return this.renderError();
    }
    }

  /**

  • 保存用户信息
  • @param user
  • @return
    */
    @RequestMapping(method = {RequestMethod.POST})
    @RequiredPerms(“user:add”)
    @ApiOperation(value=“添加用户信息”, notes=“添加用户信息”)
    @ApiImplicitParam(name = “user”, value = “用户信息”, required = true, dataType = “User”)
    public @ResponseBody JsonResult saveUser(User user) {
    userService.save(user);
    return this.renderSuccess();
    }

  /**

  • 更新用户信息
  • @param user
  • @return
    */
    @RequestMapping(method = {RequestMethod.PUT})
    @RequiredPerms(“user:update”)
    @ApiOperation(value=“更新用户信息”, notes=“更新用户信息”)
    @ApiImplicitParam(name = “user”, value = “用户信息”, required = true, dataType = “User”)
    public @ResponseBody JsonResult updateUser(User user) {
    userService.update(user);
    return this.renderSuccess();
    }

  /**

  • 删除用户信息
  • @param userId
  • @return
    */
    @RequestMapping(value = “/{userId}”, method = {RequestMethod.DELETE})
    @RequiredPerms(“user:list”)
    @ApiOperation(value=“根据UserId删除用户信息”, notes=“根据UserId删除用户信息”)
    @ApiImplicitParam(name = “userId”, value = “用户ID”, required = true, dataType = “String”, paramType = “path”)
    public @ResponseBody JsonResult removeUser(@PathVariable(“userId”) String userId) {
    userService.removeByUserId(userId);
    return this.renderSuccess();
    }

}

2. 查看Swagger 2文档

启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html

4. Swagger 2常用注解说明
   Swagger 2通过注解表明该API接口会生成文档，包括接口名称、请求方法、请求参数、返回信息的等等。

Swagger 2.0使用的注解及其说明：

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

作用范围 API 使用位置
对象属性 @ApiModelProperty 用在出入参数对象的字段上
协议集描述 @Api 用于controller类上
协议描述 @ApiOperation 用在controller的方法上
Response集 @ApiResponses 用在controller的方法上
Response @ApiResponse 用在 @ApiResponses里边
非对象参数集 @ApiImplicitParams 用在controller的方法上
非对象参数描述 @ApiImplicitParam 用在@ApiImplicitParams的方法里边
描述返回对象的意义 @ApiModel 用在返回对象类上

关于Swagger注解的使用可参考Swagger常用注解说明
更多信息可以参考【Swagger官方手册】

作者：夜影风
来源：CSDN
原文：https://blog.csdn.net/garyond/article/details/80189921
版权声明：本文为博主原创文章，转载请附上博文链接！