swagger-在spring中整合

2021年10月12日 1.1k 字大概 5 分钟

swagger的常用api以及在springboot中整合

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，端口号为自己定义的端口号。