swagger2工具书

注解

接口注解

@Api

用于描述接口组,也就是Controller类
属性

属性名 取值 作用
tags String数组 对接口组的简要说明
description String description
description String description

@ApiOperation

用于描述接口的功能,也就是Controller里的方法
属性

属性名 取值 作用
value String 对接口的简要说明
notes String 对接口的详细说明

@ApiImplicitParam

用于描述请求参数
属性

属性名 取值 作用
name 参数名
value String 参数说明
required boolean 是否必填
dataType String 数据类型
paramType 参数类型
path Rest参数
query url参数
header 请求头参数
body 请求体参数
form 表单参数
defaultValue 默认值

@ApiImplicitParams

用于描述多个请求参数
属性

属性名 取值 作用
value @ApiImplicitParam数组 聚合描述

@ApiResponse

用于描述接口错误的返回结果
属性

属性名 取值 作用
code 错误码
message 错误信息
response 异常类

@ApiResponses

用于描述有多种错误的返回结果
属性

属性名 取值 作用
value @ApiResponse数组 聚合描述

实体注解

@ApiModel

用于描述实体类,在接口的形参或返回值是该实体时,加入属性到接口说明
属性

属性名 取值 作用
value String 实体简要说明
description String 实体详细说明

@ApiModelProperty

用于描述实体的属性
属性

属性名 取值 作用
value String 属性说明
required boolean 是否必填
example String 例子

分布式聚合文档

准备工作

  1. 添加依赖
        <dependency>
            <groupId>com.didispacegroupId>
            <artifactId>swagger-butler-coreartifactId>
            <version>2.0.0version>
        dependency>
  1. 添加注解:在入口类上添加@EnableSwaggerButler
@EnableSwaggerButler
@SpringBootApplication
public class StaticApplication {
    public static void main(String[] args) {
        SpringApplication.run(StaticApplication.class);
    }
}

添加配置

swagger:
  butler:
  	# 是否根据网关路由自动生成
    auto-generate-from-zuul-routes: true
    # 文档的默认访问路径
    api-docs-path: v2/api-docs
    # 文档默认版本,一般不修改
    swagger-version: 2.0
    # 忽略的路由
    ignore-routes:
    # 手动配置文档路径
    resources:
       (文档1):
          # 服务名称,该值会添加到文档路径做前缀
          name: service1
          # 文档访问路径(不设置则采用上面配置的默认)
          api-docs-path:
          # 文档版本,(不设置则采用上面配置的默认)
          swagger-version:

使用网关获取文档

设置根据网关路由自动生成后,swagger-butler会获取所有路由的拦截路径,并在末尾添加文件访问地址,以利用网关来获取服务的swagger文档,举个例子:

网关配置:

zuul:
  routes:
    user:
      path: /user/**
      serviceId: user-service

swagger-bulter配置:

swagger:
  butler:
    auto-generate-from-zuul-routes: true
    api-docs-path: v2/api-docs

执行流程如下:

  1. 从网关配置获取到user服务的访问路径/user/**
  2. 然后添加文档访问路径v2/api-docs
  3. 得到/user/v2/api-docs,并通过网关转发user服务获取到swagger文档

访问聚合文档

初始文档:http://ip:port/swagger-ui.html
增强文档:http://ip:port/doc.html

你可能感兴趣的:(知识储备)