Swagger组件

概述

为了更好的服务于项目API管理及前后端联调，框架特此引入Knife4j。 Knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。

适用范围

Pangea v2.8.6+

快速集成

1、在业务模块的`pom`文件中添加依赖

检查所在项目的pom.xml中是否添加了pangae-common-swagger依赖，如果存在依赖则跳过此步骤，否者需要添加依赖，代码如下：

xml

<dependency>
    <groupId>com.hisense.pangea</groupId>
    <artifactId>pangea-common-swagger</artifactId>
</dependency>

2、配置参数

在项目所在的yml配置文件中配置以下参数

yaml

# swagger参数配置
pangea:
  swagger:
    #分组名称
    group-name: pangea微服务开发框架-系统服务
    #扫描路径
    base-package: com.hisense.demo.controller
    #文档标题
    title: pangea微服务开发框架-系统服务API文档
    #文档描述
    description: 此文档是系统服务下所有API接口的描述
    #系统地址
    terms-of—service-url: http://pangea.hisense.com
    #版本信息
    version: 2.0
    #作者信息
    contact:
      #作者名称
      name: 张三
      #作者邮箱
      email: zhangsan@hisense.com
      #作者主页
      url: http://www.zhangsan.com

以上参数配置为demo演示，项目组需要根据实际需求进行更改。以下为参数配置详情与示例：

中文	描述	示例
分组名称	用于各服务之间区分或各版本之间区分	pangea微服务开发框架-系统服务
swagger扫描路径	要产生Api文档的路径，一般扫描项目的controller路径	com.hisense.demo.controller
API文档表头	用于描述文档主页的标题	pangea微服务开发框架-系统服务API文档
API文档描述	用于描述文档主页的描述	此文档是系统服务下所有API接口的描述
地址	系统的访问地址或关于文档的其他地址	http://pangea.hisense.com
作者	文档的生成者	pangea@hisense.com
版本	文档的版本维护	2.0
以上参数为swagger基本参数配置，使用示例中的值产生的效果如下图，

更多参数配置框架团队正在探索中，敬请期待！

3、配置返回值统一格式白名单

将以下代码添加到项目中的application.yml文件中：

yaml

pangea:
  dispose:
    advice-filter-package:
      - springfox.documentation.swagger

至此，swagger已完成集成。此时，我们可以启动服务，等待服务启动成功后我们可以访问swagger页面，本地访问地址为http://localhost:服务端口/doc.html，信云部署后访问地址为前端地址/api/后端服务名/doc.html，例如，我们访问demo服务的api，访问地址应为http://pangea.test.devapps.hisense.com/api/demo/doc.html。访问后的页面呈现效果如下：

基本使用

1、常用注解

注解	作用
@Api	修饰整个类，描述Controller的作用，表示该类是一个swagger资源
@ApiOperation	用在请求的方法上，说明方法的用途、作用
@ApiParam	作用于请求的方法上，用于单个参数的描述
@ApiResponses	用在请求的方法上，表示一组响应
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiIgnore	使用该注解忽略这个API
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，也可单独使用，指定一个请求参数的各个方面
@ApiModel	修饰整个类，描述domain的作用，一般用于接口参数为实体对象的（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty	修饰domain中的属性，描述属性的作用，一般配合@ApiModel使用

2、注解的使用

2.1 @Api

属性名称	数据类型	默认值	说明
tags	String[]	“”	对Controller的分组，对Controller简要说明

示例：

java

@RestController
@RequestMapping("/demo")
@Api(tags = "测试Demo")
public class DemoController extends BaseController {
    
}

示例产生的效果如图

2.2 @ApiOperation

属性名称	数据类型	默认值	说明
value	String		接口简要说明，120字符或更少
notes	String	“”	接口详细描述
示例：

java

@ApiOperation(value = "删除用户", notes = "用于根据ID数组批量删除用户")
@DeleteMapping("delete")
public String delete(@RequestBody List<Long> ids) {//内部实现}

示例产生的效果如图

2.3 @ApiParam

属性名称	数据类型	默认值	说明
name	String	“”	参数名称
value	String	“”	参数简单描述
defaultValue	String	“”	描述参数默认值
required	boolean	false	是否为必传参数, false:非必传; true:必传

示例：

java

public String delete(@ApiParam(value = "用户id数组", name = "ids", required = true)@RequestBody List<Long> ids) {
    //内部实现
}

示例产生的效果如图

2.4 @ApiResponses

属性名称	数据类型	默认值	说明
value	ApiResponse[]		ApiResponse 列表

2.5 @ApiResponse

属性名称	数据类型	默认值	说明
code	int		响应码
message	String		响应信息

示例:

java

@ApiOperation(value = "删除用户", notes = "用于根据ID数组批量删除用户")
@DeleteMapping("delete")
@ApiResponses({
        @ApiResponse(code=200,message="访问成功"),
        @ApiResponse(code=204,message="服务器成功处理请求,但不需要返回任何实体内容"),
        @ApiResponse(code=400,message="请求参数没填好"),
        @ApiResponse(code=401,message="认证错误，未检测到token或token失效"),
        @ApiResponse(code=403,message="禁止访问"),
        @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对"),
        @ApiResponse(code=500,message="服务器内部错误")
})
public String delete(@ApiParam(value = "用户id数组", required = true)@RequestBody List<Long> ids) {
    //内部实现
}

示例产生的效果如图

2.6 @ApiIgnore

注解主要作用在方法上，类上，参数上。
当作用在方法上时，方法将被忽略；
作用在类上时，整个类都会被忽略；
作用在参数上时，单个具体的参数会被忽略。

2.7 @ApiImplicitParams

属性名称	数据类型	默认值	说明
value	ApiResponse[]		ApiResponse列表

2.8 @ApiImplicitParams

属性名称	数据类型	默认值	说明
name	String	“”	参数名称(实体类字段名称)
value	String	“”	参数简要说明
defaultValue	String	“”	描述参数的默认值
required	boolean	false	指定是否为必填参数,false:非必传参数; true:必传参数

2.9 @ApiModel

属性名称	数据类型	默认值	说明
value	String	类名	为模型提供备用名称
description	String	“”	提供详细的类描述

2.10 @ApiModelProperty

属性名称	数据类型	默认值	说明
value	String	“”	属性简要说明
name	String	“”	运行覆盖属性的名称。重写属性名称
dataType	String	“”	参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型
required	boolean	false	是否为必传参数,false:非必传参数; true:必传参数
position	int	0	允许在模型中显示排序属性
hidden	boolean	false	隐藏模型属性，false:不隐藏; true:隐藏

更多swagger进阶使用请参考 knife4j官方文档

Swagger组件 ​

概述 ​

适用范围 ​

快速集成 ​

1、在业务模块的pom文件中添加依赖 ​

2、配置参数 ​

3、配置返回值统一格式白名单 ​

基本使用 ​

1、常用注解 ​

2、注解的使用 ​

2.1 @Api ​

2.2 @ApiOperation ​

2.3 @ApiParam ​

2.4 @ApiResponses ​

2.5 @ApiResponse ​

2.6 @ApiIgnore ​

2.7 @ApiImplicitParams ​

2.8 @ApiImplicitParams ​

2.9 @ApiModel ​

2.10 @ApiModelProperty ​

Swagger组件

概述

适用范围

快速集成

1、在业务模块的`pom`文件中添加依赖

2、配置参数

3、配置返回值统一格式白名单

基本使用

1、常用注解

2、注解的使用

2.1 @Api

2.2 @ApiOperation

2.3 @ApiParam

2.4 @ApiResponses

2.5 @ApiResponse

2.6 @ApiIgnore

2.7 @ApiImplicitParams

2.8 @ApiImplicitParams

2.9 @ApiModel

2.10 @ApiModelProperty