spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档

一、概念综述

1.1 SpringFox

SpringFox 是一个开源的 API 文档框架, 它的前身是 Swagger-SpringMVC ,能够完美的支持 SpringMVC 并将其中接口方法自动转换为接口文档。 目前 SpringFox 正致力于对更多 JSON API 规范和标准的扩展和支持,例如:swagger,RAML 和 jsonapi。

1.2 Swagger

Swagger 是一个规范框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,支持 API 全生命周期的开发和管理。它是一个综合的开源项目,包含 swagger-core、swagger-ui、swagger-codegen、swagger-editor 等多个子项目:

  • swagger-core:Swagger Core 是 OpenAPI 规范(以前称为 Swagger 规范)的 Java 实现。

  • swagger-ui:根据可视化文档,提供与 API 资源的可视化交互。

  • swagger-codegen:开源的代码生成器,根据 Swagger 定义的 RESTful API 可以自动建立服务端和客户端的连接。

  • swagger-editor:开源的 API 文档编辑器。

下图为 swagger-ui 提供的文档可视化界面示例:

spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档_第1张图片

1.3 关联关系

OpenAPI、Swagger、SpringFox 之间的关联关系可以表述为:Swagger Core 是 Open API 规范的 Java 实现,而 SpringFox 则提供了 Swagger 与 Spring 的集成支持

二、集成 Swagger 2.0

2.1 基本依赖


<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

2.2 Swagger 配置

进行 Swagger 个性化配置,并使用 @EnableSwagger2 开启 Swagger 支持。另外,虽然 Swagger 是一个非常易用的接口调试插件,但是有可能会导致接口信息泄露,所以建议在开发环境和测试环境开启,但在生产环境关闭。这里一共给出三种 Swagger 开启和关闭的切换方法:

  1. 如下面代码所示,在配置文件中增加自定义的开关参数,并在创建 Docket 时,在链式调用的 enable() 方法中传入。
  2. 在 SwaggerConfig 配置类上添加 @Profile({"dev","test"}) 注解,指明仅在开发环境和测试环境下激活此配置,并在打包部署时使用 spring.profiles.active 指明具体的环境。
  3. 在配置文件中配置自定义的开关参数,并在 SwaggerConfig 配置类上添加 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true"),指明配置类的生效条件。@ConditionalOnProperty 注解能够控制某个配置类是否生效。具体操作是通过 name 和 havingValue 属性来实现,name 对应配置文件中的某个属性,如果该值为空,则返回 false;如果值不为空,则将该值与 havingValue 指定的值进行比较,如果一样则返回 true;否则返回 false。如果返回值为 false,则对应的配置不生效;为 true 则生效。

以下是第一种开关配置方式的使用示例:

/**
 * @description :  Swagger 配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean swaggerEnable;

    /***
     * 配置 swagger
     * 开发和测试环境下可以开启 swagger 辅助进行调试,而生产环境下可以关闭或者进行相应的权限控制,防止接口信息泄露
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.heibaiying.springboot.controller"))
                .paths(PathSelectors.any())
                .paths(doFilteringRules())
                .build();
    }

    /***
     * 接口文档的描述信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("spring boot swagger2 用例")
                .description("描述")
                .licenseUrl("https://mit-license.org/")
                .version("1.0")
                .build();
    }

    /**
     * 可以使用正则定义 url 过滤规则
     */
    private Predicate<String> doFilteringRules() {
        return not(
                regex("/ignore/*")
        );
    }
}

application.properties :

#swagger启用开关
swagger.enable = true

2.3 Swagger 注解

@Slf4j
@Api(value = "产品接口", description = "产品信息接口")
@RestController
public class ProductController {

    /***
     * 一个标准的 swagger 注解
     */
    @ApiOperation(notes = "查询所有产品", value = "产品查询接口")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "path", defaultValue = "1")
    )
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "无效的请求"),
            @ApiResponse(code = 401, message = "未经过授权认证"),
            @ApiResponse(code = 403, message = "已经过授权认证,但是没有该资源对应的访问权限"),
            @ApiResponse(code = 404, message = "服务器找不到给定的资源,商品不存在"),
            @ApiResponse(code = 500, message = "服务器错误")
    })
    @GetMapping(value = "/product/{id}", produces = "application/json")
    public ResponseEntity<Product> getProduct(@PathVariable long id) {
        Product product = new Product(id, "product" + id, new Date());
        return ResponseEntity.ok(product);
    }


    /***
     * 如果用实体类接收参数,则用实体类对应的属性名称指定参数
     */
    @ApiOperation(notes = "保存产品", value = "产品保存接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "产品编号", paramType = "body", defaultValue = "1"),
            @ApiImplicitParam(name = "name", value = "产品名称", paramType = "body"),
            @ApiImplicitParam(name = "date", value = "产品生产日期", paramType = "body")
    }
    )
    @PostMapping(value = "/product")
    public ResponseEntity<Void> saveProduct(@RequestBody Product product) {
        System.out.println(product);
        return ResponseEntity.ok().build();
    }


    /***
     * 在配置类中指明了该接口不被扫描到,可以在配置类中使用正则指定某一类符合规则的接口不被扫描到
     */
    @ApiOperation(notes = "该接口会被忽略", value = "产品保存接口")
    @PostMapping(value = "/ignore")
    public ResponseEntity<Product> ignore() {
        return ResponseEntity.ok().build();
    }

    /**
     * 不加上任何 swagger 相关的注解也会被扫描到 如果不希望被扫描到,需要用 @ApiIgnore 修饰
     */
    @PostMapping(value = "/normal")
    public ResponseEntity<Void> normal() {
        return ResponseEntity.ok().build();
    }

    @ApiIgnore
    @PostMapping(value = "/apiIgnore")
    public ResponseEntity<Void> apiIgnore() {
        return ResponseEntity.ok().build();
    }
}

Swagger 为了最大程度防止对逻辑代码的侵入,基本都是依靠注解来完成文档描述。常用注解如下:

Annotation Attribute Target Property Description
RequestHeader defaultValue Parameter#defaultValue e.g. @RequestHeader(defaultValue="${param1.defaultValue}")
ApiModelProperty value ModelProperty#description e.g. @ApiModelProperty(value="${property1.description}")
ApiModelProperty description ModelProperty#description e.g. @ApiModelProperty(notes="${property1.description}")
ApiParam value Parameter#description e.g. @ApiParam(value="${param1.description}")
ApiImplicitParam value Parameter#description e.g. @ApiImplicitParam(value="${param1.description}")
ApiOperation notes Operation#notes e.g. @ApiOperation(notes="${operation1.description}")
ApiOperation summary Operation#summary e.g. @ApiOperation(value="${operation1.summary}")
RequestParam defaultValue Parameter#defaultValue e.g. @RequestParam(defaultValue="${param1.defaultValue}")
  1. @Api:用在类上,说明该类的作用;

  2. @ApiOperation:用在方法上,说明方法的作用;

  3. @ApiParam:用在参数上,说明参数的作用;

  4. @ApiImplicitParams:用在方法上说明方法参数的作用;

  5. @ApiImplicitParam:用在 @ApiImplicitParams 注解中,描述每个具体参数;

  6. @ApiResponses:一组 @ApiResponse 的配置;

  7. @ApiResponse:请求返回的配置;

  8. @ResponseHeader:响应头的配置;

  9. @ApiModel:描述一个 Model 的信息(一般用在 post 创建的时候,使用@RequestBody 接收参数的场景);

  10. @ApiModelProperty:描述 model 的属性。

  11. @ApiIgnore:可以用于类、方法、属性,代表该方法、类、属性不被 Swagger 的文档所管理。

2.4 可视化接口文档

接口文档访问地址:http://localhost:8080/swagger-ui.html ,文档主界面如下:

spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档_第2张图片

2.5 接口测试

Swagger-UI 除了提供接口可视化的功能外,还可以用于接口测试。点击对应接口的 try it out 按钮,然后输入对应的参数的值,最后点击下方的 Execute 按钮发送请求:

spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档_第3张图片
spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档_第4张图片
POST 接口可以直接修改 Model 对应的 Json 数据 ,然后点击下方的 `Execute` 按钮发送请求:
spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档_第5张图片

附:源码GitHub地址:https://github.com/heibaiying/spring-samples-for-all

你可能感兴趣的:(spring,boot)