如何使用Swagger注释在Swagger中设置描述和示例? [英] How can I set a description and an example in Swagger with Swagger annotations?
问题描述
我正在使用Spring启动创建REST Api,并使用swagger codegen在控制器中自动生成swagger文档。但是,我无法在POST请求中为String类型的参数设置描述和示例。这是mi代码:
I am creating a REST Api using Spring boot, and auto generating the swagger documentation in controllers using swagger codegen. However, I am not able to set a description and example for a parameter of type String in a POST request. Here is mi code:
import io.swagger.annotations.*;
@Api(value = "transaction", tags = {"transaction"})
@FunctionalInterface
public interface ITransactionsApi {
@ApiOperation(value = "Places a new transaction on the system.", notes = "Creates a new transaction in the system. See the schema of the Transaction parameter for more information ", tags={ "transaction", })
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Another transaction with the same messageId already exists in the system. No transaction was created."),
@ApiResponse(code = 201, message = "The transaction has been correctly created in the system"),
@ApiResponse(code = 400, message = "The transaction schema is invalid and therefore the transaction has not been created.", response = String.class),
@ApiResponse(code = 415, message = "The content type is unsupported"),
@ApiResponse(code = 500, message = "An unexpected error has occurred. The error has been logged and is being investigated.") })
@RequestMapping(value = "/transaction",
produces = { "text/plain" },
consumes = { "application/json" },
method = RequestMethod.POST)
ResponseEntity<Void> createTransaction(
@ApiParam(
value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required." ,
example = "{foo: whatever, bar: whatever2}")
@Valid @RequestBody String kambiTransaction) throws InvalidTransactionException;
}
@ApiParam的示例属性已由我手动插入,因为codegen忽略了yaml的那一部分(那是另一个问题:为什么编辑器会忽略示例部分?)。这是yaml的一部分:
The example property of the @ApiParam has been manually inserted by me, because the codegen was ignoring that part of the yaml (That is another question: why is the editor ignoring the example part?). Here is part of the yaml:
paths:
/transaction:
post:
tags:
- transaction
summary: Place a new transaction on the system.
description: >
Creates a new transaction in the system. See the schema of the Transaction parameter
for more information
operationId: createTransaction
parameters:
- $ref: '#/parameters/transaction'
consumes:
- application/json
produces:
- text/plain
responses:
'200':
description: Another transaction with the same messageId already exists in the system. No transaction was created.
'201':
description: The transaction has been correctly created in the system
'400':
description: The transaction schema is invalid and therefore the transaction has not been created.
schema:
type: string
description: error message explaining why the request is a bad request.
'415':
description: The content type is unsupported
'500':
$ref: '#/responses/Standard500ErrorResponse'
parameters:
transaction:
name: kambiTransaction
in: body
required: true
description: A JSON value representing a kambi transaction. An example of the expected schema can be found down here. The fields marked with an * means that they are required.
schema:
type: string
example:
{
foo*: whatever,
bar: whatever2
}
最后,这就是招摇所显示的:
And finally, this is what swagger is showing:
< a href =https://i.stack.imgur.com/uw5ZU.png =noreferrer>
最后,build.gradle中使用的依赖项如下:
Finally, the dependencies used in build.gradle are the following ones:
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'
所以,问题是:
有人知道如何使用swagger注释设置描述和身体参数的示例吗?
So, Question is: Does anybody know how I can set the description and an example of a body parameter using swagger annotations?
编辑
EDIT
我已经实现了使用@Ap更改说明iImplicitParam而不是@ApiParam,但示例仍然缺失:
I've achieved to change the description using @ApiImplicitParam instead of @ApiParam, but example is still missing:
@ApiImplicitParams({
@ApiImplicitParam(
name = "kambiTransaction",
value = "A JSON value representing a transaction. An example of the expected schema can be found down here. The fields marked with * means that they are required. See the schema of KambiTransaction for more information.",
required = true,
dataType = "String",
paramType = "body",
examples = @Example(value = {@ExampleProperty(mediaType = "application/json", value = "{foo: whatever, bar: whatever2}")}))})
推荐答案
我在为身体对象生成示例时遇到了类似问题 - 注释 @Example
和 @ExampleProperty
在swagger 1.5.x中根本无法正常工作。(我使用1.5.16)
I have similar issue with generating examples for body objects - annotation @Example
and @ExampleProperty
simply doesn't work for no reason in swagger 1.5.x. (I use 1.5.16)
我的目前的解决方案是:
使用 @ApiParam(example =...)
用于非身体对象,例如:
My current solution is:
use @ApiParam(example="...")
for non-body objects, e.g.:
public void post(@PathParam("userId") @ApiParam(value = "userId", example = "4100003") Integer userId) {}
body 对象创建新类和注释字段 @ApiModelProperty(value =,example =)
,例如:
for body objects create new class and annotate fields with @ApiModelProperty(value = " ", example = " ")
, e.g.:
@ApiModel(subTypes = {BalanceUpdate.class, UserMessage.class})
class PushRequest {
@ApiModelProperty(value = "status", example = "push")
private final String status;;
}
这篇关于如何使用Swagger注释在Swagger中设置描述和示例?的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!