Adding file in openAPI schema - rest

How do i define an openAPI schema for a file? I understand that it is an object but I don't know how to define it so that the person reading the document will understand that the given request contains file in a given key.
This is my current progress but I think it is completely wrong.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
Could someone make a schema for me?
PS: I am using v3.1.0 of openAPI
Thanks!!

Related

Fastify addSchema to provide meaningful name of the OpenAPI 2.0 definition objects

I have some schema definitions created with fastify as in below, where I have used 'title' to give meaningful name of my models.
fastify.addSchema({
$id: 'persistence-query-params',
title: "PersistenceQueryParams", // Here
type: 'object',
description: 'Persistence Service GET API URL query specification. Applicable for GET API only.',
properties: {
...........
},
});
However when I am looking at the json generated from the swagger (I am using fastify-swagger: 4.8.4 and fastify: 3.20.1), I am seeing this
def-7: ## Here
title: PersistenceQueryParams
type: object
description: >-
Persistence Service GET API URL query specification. Applicable for GET
API only.
properties:
This is coming up in the OpenAPI 2.0 https://editor.swagger.io/, when loading the json generated out of that schema.
I have tried out adding the name field also:
name: "PersistenceQueryParams",
However no luck.
How can I create meaningful names, instead of def-0, def-1 etc in OpenAPI 2.0?
Thanks,
Pradip

Define OpenAPI 2.0 returning JSON object of unknown type

I want to describe OpenAPI that returns JSON object of unknown/any type.
If I define return type in the yaml below I still see generated client returning just a raw string.
responses:
200:
description: Returns any JSON object
schema:
type: string
format: object
Is there a way to describe the return type as a JSON object without describing its schema?
An arbitrary object is defined as type: object, so the correct definition is:
responses:
200:
description: Returns any JSON object
schema:
type: object
Based on Helen's answer you can also explicitly define the content type besides the actual payload being unknown. This is for OpenAPI 3.0.
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
See a full example here.

Can I get openapi3 referenced schema properties with vertx 4.0.0?

I can get the openapi3 operation model as described in the documentation,
but I would like to get the referenced schema properties.
for example I have the "post-example" operation in my yaml:
/post-example:
post:
summary: Example for all the possible 200 query responses
operationId: post-example
tags:
- read
requestBody:
required: true
content:
"application/json":
schema:
$ref: "#/components/schemas/example-query"
responses:
200:
description: Expected response to a valid request
and I would like to get the "example-query" schema properties.
Is this possible with vertx 4.0.0?
Using RouterBuilder#getOpenAPI() you can get the OpenAPIHolder, which allows you to access to any component of the OpenAPI document using JsonPointer:
OpenAPIHolder holder = routerBuilder.getOpenAPI();
Object schema = holder.getCached(
JsonPointer.from("#/components/schemas/example-query")
);

Properly create a RAML 1.0 Named Example

I am using RAML 1.0 to specify an API, but having trouble working with the Named Example fragment type. I've looked at numerous tutorials and examples, but cannot find a definitive guide to what's expected in this resource.
I'm working with the MuleSoft Anypoint Platform API Designer. (May 2020)
Here is my DataType definition:
#%RAML 1.0 DataType
type: object
properties:
display-name:
required: true
type: string
note-properties:
required: true
type: object
note-data:
required: true
type: any
Here is my Named Example fragment:
#%RAML 1.0 NamedExample
noteExample:
display-name: greeting
note-properties: read-only
note-data: Hello world
And here is the root file that references these:
#%RAML 1.0
title: sandbox API
types:
noteType: !include definitions/noteType.raml
/note:
get:
responses:
200:
body:
application/json:
type: noteType
examples: !include examples/noteExample.raml
The issue is that the parser (APIKit plugin) reports this as an error. Here is the error message from Design Center:
['note-properties'] should be object at /examples/noteExample.raml (3, 1)
I've also tried a simpler DataType definition, but I get the same error.
Is there an obvious error in my Named Example file. I know there must be a definitive spec, but so far what I find are various (occasionally conflicting) examples.
...okay, this is embarrassing. The error message tells exactly what is wrong.
It clearly says "XXX should be an object"
When I changed the Named Example to this:
#%RAML 1.0 NamedExample
noteExample:
type: object
properties:
status: read-only
note-data: Hello world
...where the value presented for
note-properties
is an actual object instead of a simple string (as it was in my OP), then that worked just fine.

openapi3: how to specify that an object schema should be a schema itself?

I want a field in a PUT body that is itself supposed to be a jsonschema. How do I formally specify this rather than putting that info in a description?
type: object
description: "..."
properties:
foo:
type: integer
create_schema:
type: object
description: >
jsonschema (following http://json-schema.org/draft-07/schema) of the CREATE payload...
OpenAPI doesn't like the schema keyword in a definition here