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.
Related
Consider HTML. You write a tag <img src="http://example.com/image.png"/> and the browser retrieves the image at the location specified. I'm designing my API to use a similar mechanism where it's up to the server where any secondary resources and it supplies the location of those resources in the form of a URL.
I'm writing an OpenAPI document to describe all the JSON structures that are sent up to and returned by the server. It works great except I don't know how to express the relationship between the URL inside the response to the first resource to the second resource.
openapi: 3.0.3
info:
title: Minimal Spec for Question.
version: 0.0.0
paths:
/firstRefToSecond:
get:
description: Gets some data including a reference to a secondary resource.
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
RefToSecond:
type: string
description: The URL to the second resource.
example: "http://example.org/second"
/secondResourceExampleUrlNotActuallyThisUrl:
get:
description:
The second resource.
Found at the URL pointed to by RefToSecond.
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
Data:
type: integer
description: The data.
example: 12
Here, the second "path" is simply a placeholder for the second URL. I would prefer not to have that placeholder at all and instead substitute the path for wherever that URL points.
Is there a way in OpenAPI to express this relationship between the "refToSecond" URL property and the requirements of what that secondary interaction would look like, without linking it to an explicit URL set in advance?
Is there a way in OpenAPI to express this relationship between the "refToSecond" URL property and the requirements of what that secondary interaction would look like, without linking it to an explicit URL set in advance?
It is possible to formally express a relationship between the response of an operation and another request URL: See the Link feature. The section "Runtime Expression Syntax" is apparently helpful for your case. (Disclaimer: I have never seen this feature being used anywhere in practice so far.)
But this only allows to express the relation to the operation that is available at the server-defined URL. You cannot specify dynamic endpoints in OpenAPI, so you cannot provide a detailed description of the request and response (except in the way you showed in the question).
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!!
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
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.
Today i got into swagger and swagger-ui to create the documentation of our API.
We are using AWS API Gateway with a Lambda function, since AWS is comming with an in-built option for documentation we are going with it.
Sadly, I am pretty limited with this option or I am doing it wrong.
As an example
responses:
'200':
description: 200 response
schema:
$ref: '#/definitions/Empty'
I can´t create an alternative schema, nor im able to edit the existing /Empty schema.
Is there a solution for my problem?
For example
... to not use an schema and just write the whole response in there?
... to show me how to create an alternative schema?
EDIT
For me it seems like an AWS problem, not my swagger file in generall. If someone reads over this i added more informations.
It doesnt matter if i use "create Documetation Part" --> Type = Response (Body) or i go to Ressources --> Method which i want to set the Response (Body) --> Method Response and set the Respone Body to an Modell.
My Modell looks like this
{
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description" : "Example Promotion",
"title" : "Promotion",
"type" : "object",
"properties" : {
"Status" : { "type" : "string"}
}
}
}
It gives me no error, but if i go to "Publish Documentation" it seems to no put the Respone (Body) i set into the swagger.json on the Method Response part, nor on the Defenitions at the end of the file and set the schema path right.
I found it easier to not use $ref when I was starting out. After you have the knack how to write requests or response definitions, you can easily transition to referencing schemas using $ref.
What comes after schema statement? That depends on what you expect to be returned -- text, an array, a JSON object, or an array of JSON objects, etc. Typically it's the later two. So here is an example of each.
schema:
type: object
description: This is a JSON object
properties:
fullName:
type: string
age:
type: number
which defines: { fullName: "Jane Smith", age: 30 }
schema:
type: array
description: This is an array of JSON object
items:
type: object
properties:
carMake:
type: string
carModel:
type: string
which defines: [{ carMake: "Ford", carModel: "Mustang" } ... ]
Clone github's swagger-ui onto your computer and run it as a local server. Or you have free use of the SwaggerHub if you don't mind the API definition to be public (or, after a trial period, pay for your APIs to be private).
The specification has changed over the years, so its important to know whether you are dealing with swagger v2 or openapi v3. www.swagger.io has a good multi-page tutorial. And you can find several public API examples at the SwaggerHub website. I do not work for Smartbear, the originators of both the original swagger spec and swaggerhub tooling, but I've found them to be very helpful in the past. Some of their staff monitor this website and answer questions.
Good luck!