Swagger使用纪要

一、常用注解说明

1、@Api

@Api:用在请求的类上,表示对类的说明
    tags="说明该类的作用,可以在UI界面上看到的注解"
    value="该参数没什么意义,在UI界面上也看不到,所以不需要配置"

在这里插入图片描述

2、@ApiOperation

@ApiOperation:用在请求的方法上,说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

在这里插入图片描述

3、@ApiImplicitParams

1)注解基础说明

@ApiImplicitParams:用在请求的方法上,表示一组参数说明
    @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
        name:参数名
        value:参数的汉字说明、解释
        required:参数是否必须传
        paramType:参数放在哪个地方
            · header --> 请求参数的获取:@RequestHeader
            · query --> 请求参数的获取:@RequestParam
            · path(用于restful接口)--> 请求参数的获取:@PathVariable
            · body(不常用)
            · form(不常用)    
        dataType:参数类型,默认String,其它值dataType="Integer"       
        defaultValue:参数的默认值

在这里插入图片描述

2)@ApiImplicitParam属性dataType单独使用会出现的bug说明

  • 问题描述

如果你的项目模块,swagger配置了分组,如下图
在这里插入图片描述

其效果
在这里插入图片描述
这时,swagger有一个非常坑的bug:你的注解@ApiImplicitParam属性dataType,不能单独使用,否则会引起一个前端错误、导致当前分组Api文档无法显示(页面会停留在点击前的页面、不跳转)。
bug截图
在这里插入图片描述

  • 解决方式
    如果要设置分组,那么使用@ApiImplicitParam注解时,dataType属性要么不使用,要么就和paramType属性一起使用
    这个应该时swagger的一个bug,并没有逻辑性,我是通过一次一次测试得到的结果。(花了整整一天时机做这种没意义的事,希望大家不用重蹈覆辙~)
    下面把测试截图记录一下,当时已知name和value属性是干净的,dataType单独使用不行、必须和paramType组合使用:
    a、怀疑是dataType位置导致的,做以下测试,发现bug没有修复;
    在这里插入图片描述
    b、又想是不是dataType和required属性组合也可以,做以下测试,bug没有修复
    在这里插入图片描述
    b、经测试,配置分组后@ApiImplicitParam注解的dataType属性就只能和paramType属性一起使用,或者不使用;单独使用就会引发上述错误。与属性先后顺序(位置)无关。

3.5、@ApiImplicitParams常用配套参数@ApiIgnore和@ApiModelProperty属性hidden

1)痛点

使用@ApiImplicitParam注解备注参数后,文档会有这样的问题:就是注解的备注会显示,方法形参也会显示(名称相同就显示一个)。这样会导致api文档特别冗余,很难读、还容易引发歧义,而且与我们的初衷也不相符,我都用@ApiImplicitParam注解了,肯定是希望以注解的备注为准啊,形参的显示混淆了视听。
在这里插入图片描述
在这里插入图片描述

2)解决

这时我们肯定想,其实不是入参的字段在swagger文档中隐藏掉;可以用以下几种方法。(隐藏,是指不在swagger接口文档中显示)
a、使用@ApiIgnore注解(最简单实用)
该注解用在方法的形参列表,它会将其后的参数隐藏掉;如果注解后是一个实体类,那么该实体类的所有字段都会被隐藏。
在这里插入图片描述
在这里插入图片描述
b、使用@ApiModelProperty的hidden属性
如果你的接口参数是用实体类接收的,那么你可以在字段上使用@ApiModelProperty注解,并将其属性hidden值设为true,这样该字段就会在swagger文档上隐藏了。
但是这个方法有个问题,当实体类字段特别多时,那你就需要加非常多@ApiModelProperty注解才能把它们全部隐藏。
不过它也有适用场景,当你不用@ApiImplicitParam注解备注接口入参、就用@ApiModelProperty注解备注时,你就可以用hidden属性将实体类中不是入参的其他字段隐藏掉。
在这里插入图片描述

4、@ApiModel

@ApiModel:用于类,表示对类进行说明,用于参数用实体类接收 
	value:表示对象名 
	description:描述 

在这里插入图片描述
在这里插入图片描述

5、@ApiModelProperty

@ApiModelProperty:用于字段; 表示对model属性的说明或者数据操作更改 
	value:字段说明 
	name:重写属性名字(实测没什么用,seagger会自动强制写属性名) 
	dataType:重写属性类型 (也没什么用,seagger会自动强制写属性类型)
	required:是否必填,Boolean类型,默认flase(必填字段会有个*)
	example:举例说明(可以给一个字段值示例)
	hidden:是否隐藏,Boolean类型,默认flase

在这里插入图片描述

6、@ApiModel

@ApiModel:用于响应类上,表示一个返回响应数据的信息
            (这种一般用在post创建的时候,使用@RequestBody这样的场景,
            请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiModelProperty:用在属性上,描述响应类的属性
  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Swagger是一个用于设计、构建和文档化RESTful Web服务的开源工具集。下面是一个简单的Swagger使用教程: 1. 安装Swagger:可以通过npm、pip等包管理工具安装Swagger相关的库和工具。例如,对于Node.js项目,可以使用以下命令安装swagger-jsdoc和swagger-ui-express: ```bash npm install swagger-jsdoc swagger-ui-express ``` 2. 编写Swagger注解:在你的API代码中,使用Swagger注解来描述API的信息、请求和响应参数等。以下是一个示例: ```javascript /** * @swagger * /api/users: * get: * summary: 获取所有用户 * description: 获取所有用户列表 * responses: * 200: * description: 成功获取用户列表 * schema: * type: array * items: * $ref: '#/definitions/User' */ ``` 在这个示例中,我们使用Swagger注解来描述一个GET请求,它可以获取所有用户的列表。 3. 生成Swagger文档:使用Swagger注解编写完API代码后,可以使用相应的工具将这些注解转换为Swagger文档。例如,对于Node.js项目,我们可以使用swagger-jsdoc库生成Swagger文档。在项目的入口文件中添加以下代码: ```javascript const swaggerJSDoc = require('swagger-jsdoc'); const swaggerUi = require('swagger-ui-express'); const options = { definition: { openapi: '3.0.0', info: { title: 'API文档', version: '1.0.0', }, }, apis: ['./path/to/api/controllers/*.js'], // API代码文件的路径 }; const swaggerSpec = swaggerJSDoc(options); app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec)); ``` 这段代码将会在`/api-docs`路径下提供Swagger文档。 4. 查看Swagger文档:运行项目并访问`/api-docs`路径,你将会看到生成的Swagger文档。Swagger提供了一个交互式的UI界面,可以方便地查看API的信息、请求和响应参数等。 这只是一个简单的Swagger使用教程,你可以根据自己的项目需求进一步深入学习和使用Swagger

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值