swagger-Api文档工具的使用

swagger-Api文档工具的使用

1. Swagger 介绍

很多人都以为 Swagger 只是一个接口文档生成框架，其实并不是。 Swagger 是一个围绕着 OpenAPI Specification（OAS，中文也称 OpenAPI规范）构建的一组开源工具。可以帮助你从 API 的设计到 API 文档的输出再到 API 的测试，直至最后的 API 部署等整个 API 的开发周期提供相应的解决方案，是一个庞大的项目。 Swagger 不仅免费，而且开源，不管你是企业用户还是个人玩家，都可以使用 Swagger 提供的方案构建令人惊艳的 REST API。

Swagger 有几个主要的产品。

• Swagger Editor – 一个基于浏览器的 Open API 规范编辑器。
• Swagger UI – 一个将 OpenAPI 规范呈现为可交互在线文档的工具。
• Swagger Codegen – 一个根据 OpenAPI 生成调用代码的工具。

如果你想了解更多信息，可以访问 Swagger 官方网站 swagger.io。

2. Springfox 介绍

源于 Java 中 Spring 框架的流行，让一个叫做 Marrty Pitt 的老外有了为 SpringMVC 添加接口描述的想法，因此他创建了一个遵守 OpenAPI 规范（OAS）的项目，取名为 swagger-springmvc，这个项目可以让 Spring 项目自动生成 JSON 格式的 OpenAPI 文档。这个框架也仿照了 Spring 项目的开发习惯，使用注解来进行信息配置。

后来这个项目发展成为 Springfox，再后来扩展出 springfox-swagger2 ，为了让 JSON 格式的 API 文档更好的呈现，又出现了 springfox-swagger-ui 用来展示和测试生成的 OpenAPI 。这里的 springfox-swagger-ui 其实就是上面介绍的 Swagger-ui，只是它被通过 webjar 的方式打包到 jar 包内，并通过 maven 的方式引入进来。

上面提到了 Springfox-swagger2 也是通过注解进行信息配置的，那么是怎么使用的呢？下面列举常用的一些注解，这些注解在下面的 Springboot 整合 Swagger 中会用到。

注解	示例	描述
@ApiModel	@ApiModel(value = “用户对象”)	描述一个实体对象
@ApiModelProperty	@ApiModelProperty(value = “用户ID”, required = true, example = “1000”)	描述属性信息，执行描述，是否必须，给出示例
@Api	@Api(value = “用户操作 API(v1)”, tags = “用户操作接口”)	用在接口类上，为接口类添加描述,表示为swagger资源
@ApiOperation	@ApiOperation(value = “新增用户”)	描述类的一个方法或者说一个接口，表示一个http请求的操作
@ApiParam	@ApiParam(name=“参数名”,value = “参数说明”, required = ”是否必填“)	描述单个参数
@ApiImplicitParam	ApiImplicitParam(name=“参数” value=“参数说明” dataType=“数据类型” paramType=“参数类型” example=“举例说明”)	用于方法表示单独的请求参数

更多的 Springfox 介绍，可以访问 Springfox 官方网站。

http://springfox.github.io/springfox/docs/current/

3. 在spring中整合

3.1. 添加swagger和swagger-ui依赖

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

3.2. 添加swagger配置

package com.knox.aurora.common.swagger;

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;

/**
 * Swagger
 * <p>
 * 访问地址：http://ip:port/swagger-ui.html
 *
 * @author Knox
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.knox.aurora.controller"))
                //扫描接口路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")//标题
                .description("前端联调RESTFul接口")//描述
                .version("v1.0")//自定义版本
                .contact(new Contact("zh", "", "zh <1066771757@qq.com>"))//作者信息
                .build();
    }

}

3.3. 在controller层加入api注解

@RestController
@RequestMapping("/user")
@Api(tags = "UserController", description = "账号处理器")
{
    @ApiOperation(value = "用户登录")
    @RequestMapping(value = "/login", method = RequestMethod.POST)
    public ApiResult<Map<String, String>> login(@Valid @RequestBody LoginDTO dto) {
        String token = iUmsUserService.executeLogin(dto);
        if (ObjectUtils.isEmpty(token)) {
            return ApiResult.failed("账号密码错误");
        }
        Map<String, String> map = new HashMap<>(16);
        map.put("token", token);
        return ApiResult.success(map, "登录成功");
    }
}

3.4. 查看生产的api文档

上面操作完成后启动项目，访问http://localhost:8080/swagger-ui.html，端口号为自己定义的端口号。