1、引入依赖
<dependency> <groupId>io.ifa.chaos.starters</groupId> <artifactId>chaos-starter-swagger</artifactId> <version>1.0</version> </dependency>
2、在bootstrap.yaml配置文件中添加配置信息
swagger: title: 标题 description: 描述 scan-packages: 扫描的包,例com.yang.xxx
3、在对应的controller上添加@Api的注解
例如@Api("测试")
4、在对应controller的方法上添加@ApiOperation注解
5、进入swagger-ui测试
在浏览器输入http://127.0.0.1:8080/swagger-ui.html即可
这个ip+端口号是服务启动的地址和端口号。
6、swagger-ui注解说明:
@Api
标识这个类是 swagger 的资源,用于 controller 类上,对请求类的说明
@ApiOperation(value = "查询数据", notes = "查询类型为 type,code 编码的下一级的数据", httpMethod = "GET")
用于方法上
--value:接口描述
--notes:提示内容
--tags:分组(视情况而用)
--httpMethod:接口请求方式
@ApiImplicitParams
包含多个 @ApiImplicitParam,用于方法上
@ApiImplicitParam
表示单独的请求参数,用于方法上
--name:参数名称
--value:参数说明
--paramType:参数类型
可选值:
--header:请求参数的获取:@RequestHeader(代码中接收注解)
--query:请求参数的获取:@RequestParam(代码中接收注解)
--path:用于restful接口)-->请求参数的获取:@PathVariable(代码中接收注解)
--body:请求参数的获取:@RequestBody(代码中接收注解)
--form:(不常用)
--required:是否必传
--true
--false
--dataType:数据类型
@ApiModel
用在JavaBean类上,说明JavaBean的 用途(这种一般用在 post 创建的时候,使用 @RequestBody 这样的场景, 请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 )
--value:model的别名,默认为类名
--description:model的详细描述
@ApiModelProperty
对model属性的注解
--value:属性简短描述
--name:属性名
--dataType:属性类型
--example:属性的示例值
--required:是否为必须值
@ApiParam
增加对参数的元信息说明。这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下
--name:参数名
--value:参数简短说明
--required:是否必须
@ApiResponses
注解@ApiResponse的包装类,数组结构。即使需要使用一个@ApiResponse注解,也需要将@ApiResponse注解包含在注解@ApiResponses内。
@ApiResponse
描述一个操作可能的返回结果。当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。
如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。
--code:HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
--message:更加易于理解的文本消息
--response:返回类型信息
--responseContainer:如果返回类型为容器类型,可以设置相应的值。有效值为 "List", "Set" or "Map",其他任何无效的值都会被忽略
其他注解:
@ApiIgnore
用于于类或者方法上,可以不被 swagger 显示在页面上