Spring Boot中使用Swagger2构建RESTful APIs

关于 Swagger

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

下面我们开始在Spring Boot中使用Swagger2 构建RESTful APIs

第一步，在pom.xml中加入Swagger2的依赖

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

第二步，创建Swagger2配置类（注意配置类须与application同级目录）

/**
 * Swagger2配置类
 * 在于Springboot集成时，需与application同目录
 * 通过注解@Configuration，让Spring来加载该配置
 * 通过注解@EnableSwagger2，来启动swagger2
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 创建API应用
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.web"))//注：该路径指定为需要加载Swagger的路径，只有路径中的API才会被Swagger管理
                .paths(PathSelectors.any()).build();
        return docket;
    }

    /**
     * 创建改API的基本信息（这些基本信息会展示在文档页面中）
     * 访问地址： http://项目实际地址/swagger-ui.html
     * @return
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("了解更多请联系：Misme")
                .termsOfServiceUrl("http://www.cnblogs.com/MisMe/")
                .contact("Misme")
                .version("1.0")
                .build();
    }
}

第三步，添加文档内容，在需要的地方添加注解

@Api("ChatInfoController|图片和音频上传控制器类")
@RestController
public class ChatInfoController {

    /**
     * 上传图片接口
     * @param attach 文件对象
     * @param request http请求
     * @return imgSrc：上传后图片文件的路径
     */
    @ApiOperation(value = "上传图片",notes = "文件不能超过20M大小，后缀名为png，jpg，gif")
    @RequestMapping(value = "/uploadImg",method = RequestMethod.POST)
    @ResponseBody
    public String uploadImg(@RequestParam("file") MultipartFile attach, HttpServletRequest request) {
        System.out.println("上传图片");
        return "具体方法";
    }
}

注解详解：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

第四步，启动后访问： http://项目实际地址/swagger-ui.html，即可看见Swagger的管理页面，如果未看见管理的API请检查第二步的
apis(RequestHandlerSelectors.basePackage("com.web")) 路径是否正确；