笔记swagger

Swagger

一、简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

二、集成

1.引入依赖

 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

2.创建配置类

3.访问可视化界面

http://localhost:8586/swagger-ui.html

三、注解详解

1.@Api

• 作用: 用来指定接口的描述文字

• 修饰范围: 用在类上

  @RestController
  @Api(description = "学历学位信息表相关接口")
  @RequestMapping(value = "/pe-person-edu")
  public class PePersonEduController {
  }
  

2.@ApiOperation

• 作用: 用来对接口中具体方法做描述
• 修饰范围: 用在方法上

@GetMapping("get/{guid}")
    @ApiOperation("获取一条学历学位信息表数据")
    @ApiImplicitParam(value = "主键", paramType = "path", name = "guid", dataType = "String", required = true)
    public ApiResult getPePersonEdu(@PathVariable String guid) {
        return pePersonEduService.getPePersonEdu(guid);
    }

value: 用来对接口的说明

notes:用来对接口的详细描述

3.@ApiImplicitParams

包含多个ApiImplicitParam

4.@ApiImplicitParam

• 作用: 用来对接口中参数进行说明
• 修饰范围: 用在方法上

@PostMapping("find")
    @ApiOperation("分页查询学历学位信息表数据")
    @ApiImplicitParam(value = "查询条件", paramType = "body", name = "pePersonEduQuery", dataType = "PePersonEduQuery", required = true)
    public ApiResult findPePersonEdu(@RequestBody PePersonEduQuery pePersonEduQuery) {
        return pePersonEduService.findPePersonEdu(pePersonEduQuery);
   }

name : 参数名

value: 参数说明

dataType: 参数的数据类型

paramType: 查询参数类型

path    以地址的形式提交数据
query   直接跟参数完成自动映射赋值
body    以流的形式提交 仅支持POST
header  参数在request headers 里边提交
form    以form表单的形式提交 仅支持POST

required :参数是否必填。 true 必填

5.@ApiResponses

用于返回一组响应信息

6. @ApiResponse

一般用于表达一个错误的响应信息

• 作用：用于请求的方法上，表示一组响应
• 修饰范围: 用在方法上

 @ApiResponses({@ApiResponse(code = 400,message = "参数出错"),
            @ApiResponse(code = 500,message = "路径出错")}
            )

response：返回的对象信息

code： 响应的HTTP状态码

message：返回的文本信息

reference : 指定对响应类型的引用，指定的应用可以使本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的response()类

responseHeaders : 可能响应的 header 列表

responseContainer : 声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略

7.@ApiModel

• 作用：用对象来接收参数 ，修饰类
• 修饰范围: 用在实体类上

@ApiModel("部门人员情况主表")

8.ApiModelProperty

• 作用： 用对象接收参数时，描述对象的一个字段
• 修饰范围: 用在字段上

@ApiModelProperty(value = "参加工作时间", required = false)