Я создаю REST Api, используя Spring boot, и автоматически генерирую документацию swagger в контроллерах, используя swagger codegen. Однако я не могу установить описание и пример для параметра типа String в запросе POST. Вот ми код:
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 (Это другой вопрос: почему редактор игнорирует часть примера?). Вот часть Ямла:
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
}
И, наконец, вот что показывает чванство:
Наконец, зависимости, используемые в build.gradle, следующие:
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.7.0'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.7.0'
Итак, вопрос: кто-нибудь знает, как я могу установить описание и пример параметра тела, используя аннотации чванства?
РЕДАКТИРОВАТЬ
Мне удалось изменить описание, используя @ApiImplicitParam вместо @ApiParam, но пример по-прежнему отсутствует:
@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}")}))})