1. 引言

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

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

• 对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
• API接口返回信息不明确
• 缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
• 接口文档太多，不便于管理

为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

Swagger具有以下优点：

• 功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
• 及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
• 整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

当然也不能说Swagger就一定是完美的，它也有缺点，最明显的就是代码移入性比较强。

2. Swagger 2.0 集成配置

1. 添加Swagger2的Maven依赖

在Spring Boot项目中需要添加的依赖为Swagger 2核心包和swagger-ui界面包。

<dependencies>
       ... 项目其他依赖包 ...
       <!-- Swagger2 -->
       <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>
<dependencies>

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接口定义与展示

1. 在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<User> 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

Swagger文档展示

接口详情

4. Swagger 2常用注解说明

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

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

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

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