I'm using OAS3 codegenerator to create Kotlin server code for a request containing both a file-upload, and a free-form json object that can contain arbitrary values. According to the swagger documentation, I should be able to create a free-form object that using type: object and additionalProperties : true.
However if I edit the upload photos endpoint in modules/openapi-generator/src/test/resources/3_0/petstore.yaml in the oas3 codegen samples like this
requestBody:
content:
multipart/form-data:
schema:
properties:
file:
description: file to upload
type: string
format: binary
additionalMetadata:
description: Additional data to pass to server
type: object <-- CHANGED FROM STRING
additionalProperties: true <-- ADDED
and run ./bin/generate-samples.sh ./bin/configs/kotlin-server-jaxrs-spec.yaml
the additionalMetadata field is dropped from PetApi
#POST
#Consumes("multipart/form-data")
#Produces("application/json")
suspend fun uploadFile(#PathParam("petId") petId: kotlin.Long, #FormParam(value = "file") fileInputStream: InputStream?): Response {
Is there a problem with how I'm specifying the request?
Related
I'm currently trying to make an API doc page thanks to nelmio-api-bundle. I only have one route which is a POST route. I'm receiving a JSON in the body of the request and I'm using the Serializer from symfony to deserialize it in a DTO. I'm also using a DTO for the response (which contains the status code, a bool set to true or false, and a message). Now I'm trying to use these DTO (for input and output) to build the API documentation with nelmio-api-bundle but how to make it ? I'm using PHP8.1 attributes to make it, for response it almost works (except that the response is shows as an array) but I don't know how to make it for the inputs.
Here is my current code:
#[Route('/user', methods: ['POST'])]
#[OA\Parameter(
name: 'user',
description: 'The user information in JSON',
in: 'query',
required: true
)]
#[OA\Response(
response: 200,
description: 'Returns the success response',
content: new OA\JsonContent(
type: 'array',
items: new OA\Items(ref: new Model(type: SuccessResponseDTO::class))
)
)]
public function registerUser(Request $request, LoggerInterface $logger): JsonResponse
{
//the code to register the user
}
And here is the result:
Do someone know how to make it ?
I am using openapi 3.0 to write the swagger yaml file. But upload files feature doesnot work. the swagger ui does not display the upload button as expected. below is my swagger yaml code snippet. Can someone help to take a look? Thanks!!!
/uploadfiles:
post:
requestBody:
content:
multipart/form-data:
schema:
required:
- file_list
- statement_terminator
properties:
statement_terminator:
type: string
default_schema:
type: string
encoding_type:
type: string
file_list:
type: array
items:
type: string
format: binary
required: true
Add type: object to your multipart body schema:
multipart/form-data:
schema:
type: object # <------
required:
- ...
Trying to use Swagger on my JAX-RS application with enunciate Maven plugin.
The generated JSON definition works well.
But when I try to validate it online with Swagger Editor, the converted YAML file has some weird errors.
For example:
Definition:
parameters:
- name: body
in: body
type: file
description: 'Bla bla'
responses:
'201':
ERROR:
Parameters with "type: file" must have "in: formData"
JAX-RS Code:
#POST
#Path(value = "/validatedata")
public Response validate(ValidateDataFromInput validateDataFromInput) throws CustomException {
return Response.status(Status.ACCEPTED).entity(validationActionService.getDataFromInput(validateDataFromInput.getConsumerInput(),
validateDataFromInput.getValidateInput(), null)).build();
}
I am using: swagger-core-1.5.21 and enunciate-maven-plugin-2.11.1.
Not sure which is wrong here.
I am writing API Document by Swagger.
I defined the Response format is:
definitions:
ResponseFormat:
type: object
properties:
name:
type: string
msg:
type: string
description: Error or success message
data:
type: object
Then, for each API, the format of data (object) will change. How can I change it.
Thank you!
I'm writing some REST documentation with RAML but I'm stuck.
My problem:
- I have a GET request used for search that can take a parameter "id" or (exclusive or) "reference". Having only one of them is required.
I know how to say "this param is required" but I don't know how to say "having one of these params is required". Is it even possible?
The following example written in RAML 1.0 defines two object types in Url and File then creates another object Item which requires Url OR File in ext. If you change the included examples (which currently validate), you'll see that they fail if the property does not conform to one or the other definition. Hope that helps! LMK if you have any other questions and I'll do my best.
[EDIT: hmm I think I am seeing your problem now, the final example I've just added, named should_fail, (which has one of each type together in the example) still validates and you want a way to make it fail validation.]
[UPDATE: OK I figured a mildly hacky way to do this. Use maxProperties: 1 in the object which should have properties appear alone, see updated code below which fails the final example during validation.]
#%RAML 1.0
types:
Url:
properties:
url:
type: string
example: http://www.cats.com/kittens.jpg
description: |
The url to ingest.
File:
properties:
filename:
type: string
example: kittens.jpg
description: |
Name of the file that will be uploaded.
Item:
description: |
An example of a allowing multiple types yet requiring
one AND ONLY one of two possible types using RAML 1.0
properties:
ext:
maxProperties: 1
type: File | Url
examples:
file_example:
content:
ext:
filename: video.mp4
url_example:
content:
ext:
url: http://heres.a.url.com/asset.jpg
should_fail:
content:
ext:
url: http://heres.a.url.com/asset.jpg
filename: video.mp4
I had the same problem. User can provide either a textual input OR a file input, but not both.
Both have different fields and I detect the request type from the field names. i.e if the request has [files and parameters], it is a FileInput. If the request has [texts and parameters], it is a TextInput. It is not allowed to provide both text and file within the same request.
I used the union property. See CatAndDog example in
Raml 200 documentation for a small example.
You can define your types as follows.
types:
FileInput:
properties:
parameters:
type: Parameters
description: (...)
files:
type: ArchiveCollection | FileCollection
description: (...)
TextInput:
properties:
parameters:
type: Parameters
description: (...)
texts:
type: TextCollection
description: (...)
Then in my POST request body:
/your_route:
post:
body:
multipart/form-data:
type: TextInput | FileInput
The fields in the body are defined with either TextInput or FileInput type.
In RAML 0.8 you can not describe queryParameters with only one parameter.
In RAML 1.0 you can do this. You should use oneOf in jsonschema for describing Type. Your queryParameters should use this type. Example:
api.raml
#%RAML 1.0
title: AUTH microservice
mediaType: application/json
protocols: [HTTPS]
types:
- example: !include schemas/example.json
/example:
get:
queryParameters:
type: example
schemas/example.json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"id": "file://schemas/credentials.json",
"oneOf": [
{
"properties": {"key1": {"type": "string"}},
"additionalProperties": false
},
{
"properties": {"key2": {"type": "string"}},
"additionalProperties": false
}
]
}
Also you can use uriParameters. Maybe it will help in your case.
#%RAML 0.8
title: API Using media type in the URL
version: v1
/users{mediaTypeExtension}:
uriParameters:
mediaTypeExtension:
enum: [ .json, .xml ]
description: Use .json to specify application/json or .xml to specify text/xml