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:
- ...
Related
Is it possible to assign a customised name to a Components object in OpenAPI?
I currently have two Component objects that specify a request schema:
Request1:
type: object
description: Request 1
properties:
a:
description: Filter 1 a
$ref: '#/definitions/Filter1a'
b:
description: Filter 1 b.
$ref: '#/definitions/Filter1b'
Request2:
type: object
description: Request 2
properties:
query:
type: object
description: Filter 2.
properties:
bool:
type: object
properties:
must:
type: array
items:
type: object
properties:
match_all:
type: object
In the endpoint description I refer to these schemas as follows:
/v2/myEndpoint:
post:
tags:
- some tags
operationId: someId
summary: Some summary
description: Some description
produces:
- application/json
parameters:
- in: body
name: body
required: false
schema:
oneOf:
- $ref: '#/definitions/Request1'
- $ref: '#/definitions/Request2'
When I publish the yaml file, the UI shows Request1 and Request2 in selection tabs, which carry the names 'Request1' and 'Request2'. Is it possible to assign custom names to them, so that the UI will show the custom names instead? For example 'Custom name request 1' and 'Custom name request 2'?
Many thanks!
I assume you meant Swagger UI.
title would do that. Link to Open Api Spec.
Request1:
title: Custom name request 1
type:...
Request2:
title: Custom name request 2
type:...
I'm trying to write my first Asyncapi documentation file. I'd like to perform reusability of my schema between a reusableModel and others. However, the html documentation preview gives me an array with separate objects instead of one unified object. Here is my problematic yaml content:
asyncapi: 2.0.0
info:
title: woaw
version: 0.1.0
description: >
blabla
license:
name: UNLICENSED
defaultContentType: application/json
channels:
myChannel:
subscribe:
message:
oneOf:
- $ref: '#/components/messages/new'
- $ref: '#/components/messages/deleted'
components:
messages:
new:
payload:
$ref: '#/components/schemas/new'
deleted:
payload:
$ref: '#/components/schemas/deleted'
schemas:
reusableModel:
type: object
properties:
id:
type: string
format: uuid
example: 37a2005e-70e6-4cf3-b7e3-19e087879e50
new:
allOf:
- $ref: '#/components/schemas/reusableModel'
- type: object
properties:
type:
type: string
enum: ["extension.new"]
data:
type: object
properties:
key1:
type: object
properties:
users:
type: array
items:
type: string
deleted:
allOf:
- $ref: '#/components/schemas/reusableModel'
- type: object
properties:
type:
type: string
enum: ["extension.deleted"]
data:
type: object
properties:
key1:
type: string
You might copy/paste it to https://playground/asyncapi.io to see the rendering problem. The allOf object defined in the payload of the first messageType (new) appears as an array with in part 0 the reusableModel and in part 1 the rest of my properties (type + data) and not as unified object. The documentation involves the following:
The AsyncAPI Specification allows combining and extending model definitions using the allOf property of JSON Schema, in effect offering model composition. allOf takes in an array of object definitions that are validated independently but together compose a single object.
I think I misunderstand some part of the documentation, can you explain to me ?
As I've commented, it looks like a known issue:
https://github.com/asyncapi/html-template/issues/11
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
I'm defining a resource that you POST to with a non-JSON body. It's just a string like form parameters. Something like what happens with OAuth:
grant_type=&code=&redirect_uri=
How can I document that on Swagger? Do I have to use formParam format instead of body? Everything I put into body it converts to JSON examples.
TokenRequest:
properties:
grant_type:
type: string
description: OAuth Grant Type
enum:
- authorization_code
- refresh
code:
type: string
description: Authorization Code obtained from /authorize required if grant_type = au
redirect_uri:
type: string
description: Defined Redirect URI Example - https://example.com/callback
refresh_token:
type: string
description: Required if grant_type = refresh
Here is an example on how to document the form data:
post:
tags:
- pet
summary: Updates a pet in the store with form data
description: ''
operationId: updatePetWithForm
consumes:
- application/x-www-form-urlencoded
produces:
- application/xml
- application/json
parameters:
- name: petId
in: path
description: ID of pet that needs to be updated
required: true
type: integer
format: int64
- name: name
in: formData
description: Updated name of the pet
required: false
type: string
- name: status
in: formData
description: Updated status of the pet
required: false
type: string
responses:
'405':
description: Invalid input
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'
But in your case, it seems you want to define OAuth setting so please refer to Swagger Spec 2.0 for more information. Here is an example for PetStore:
securityDefinitions:
petstore_auth:
type: oauth2
authorizationUrl: 'http://petstore.swagger.io/api/oauth/dialog'
flow: implicit
scopes:
'write:pets': modify pets in your account
'read:pets': read your pets
api_key:
type: apiKey
name: api_key
in: header