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>

2. 添加注解：在入口类上添加@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