接口文档神器---Swagger注解使用与实例

最新推荐文章于 2023-08-07 22:50:13 发布

阳光下的米雪

最新推荐文章于 2023-08-07 22:50:13 发布

阅读量1.2k

点赞数

分类专栏： Swagger 文章标签： java spring restful 注解 swagger2

本文链接：https://blog.youkuaiyun.com/qq_38530648/article/details/121694526

版权

Swagger 专栏收录该内容

7 篇文章

订阅专栏

Swagger注解

Springfox Swagger

Spring使用Springfox-swagger集成Swagger
Springfox通过扫描注解生成Api文档
Springfox包含方法参数对象注解

Swagger2整体注解

请求类注解（主要用在controller）

@ApiI标识Swagger识别的类
@Api放在@Controller注解并列的请求类
核心参数包含value、tags、description

/**
 * @Api:用在请求的类上，表示对类的说明，也代表这个类是swagger2的资源
 * 参数：
 * tags:说明该类的作用，参数是个数组，可以填多个
 * value="该参数没有什么意义，在UI界面上不显示，所以不用配置"
 * description="用户的基本信息操作"
 */
@RestController
@RequestMapping("/exam")
@Api(value = "考试预约信息服务接口", tags = "考试预约信息服务接口",)
public class ExamAppointmentInfoController {}

请求方法注解（主要用在controller里的方法上）

@ApiOperation标识Swagger识别方法

/**
 * @ApiOperation：使用于在方法上，表示一个http请求的操作
 * value:用于方法描述
 * notes:用于提示内容
 * tags:可以重新分组
 * 与Controller中的方法并列使用
 */
@ApiOperation(value = "分页查询考试预约信息", notes = "分页查询考试预约信息", produces = "application/json")

@ApiImplicitParam标识方法的参数的说明

/**
 * @ApiImplicitParam：作用在方法上，表示单独的请求参数  
 * name ：参数名。 
 * value ： 参数的具体意义，作用。 
 * required ： 参数是否必填。 
 * dataType ：参数的数据类型。 
 * paramType ：查询参数类型，见如下表格
 * @ApiImplicitParams：用于方法，包含多个 @ApiImplicitParam
 * 
*/
    @ApiOperation("获取用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhangsan"),
        @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="123456")
    })
    @RequestMapping(value="/getUser",method=RequestMethod.GET)
    public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) {
}

paramType类型如下：

类型	作用	作用
header	参数在request headers 里边提交	请求参数的获取：@RequestHeader
query	直接跟参数完成自动映射赋值	请求参数的获取：@RequestParam
path	以地址的形式提交数据	请求参数的获取：@PathVariable
body	以流的形式提交仅支持POST	–
form	以form表单的形式提交仅支持POST	–
query	直接跟参数完成自动映射赋值	–

@ApiResponse标识方法返回值的说明

/**
 - @ApiResponses: 用于表示一组响应
 - @ApiResponse:用在@ApiResponses中，一般用于表达一个错误的响应信息
 - code：数字，例如400
 - message：信息，例如"请求参数没填好"
 - response：抛出异常的类
 */
 @ApiResponses({
        @ApiResponse(code=400,message="请求参数没填好"),
        @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
    })

@ApiParam标识Controller中方法的参数说明

/**
 - @ApiParam：使用在方法上或者参数上，字段说明；表示对参数的添加元数据（说明或是否必填等）
 - name：参数名
 - value：参数说明
 - required：是否必填
 */
  public BaseResult<Boolean> existTrainingTime(@ApiParam(name = "sfzmhm",value = "身份证明号码",required = true) String sfzmhm){}

对象类注解（主要用在java bean上）

@ApiModel标识Swagger识别的JavaBean
@ApiModel放在JavaBean的类定义上
@ApiModelProperty标识JavaBean的属性

@ApiModel(description = "考试预约信息分页查询参数",value = "考试预约信息分页查询参数对象")
public class ExamAppointmentInfoValidator {

    @Min(value = 1, message = "当前页码必须为正整数")
    private Integer pageNo;
    @Min(value = 1, message = "每页条数必须为正整数")
    private Integer pageSize;

    @ApiModelProperty("身份证明号码")
    private String sfzmhm;
    @ApiModelProperty("姓名")
    private String xm;
    }