As far as I know there is no way to attach few keys to the single value in {key : value} pair in YAML.
I am new to Swagger documentation (OpenAPI 3.0) and wondering is it possible somehow to combine my values together.
For instance, I am messing with REST API documentation and when I want to list few responses without rewriting it every time, I have the following :
paths:
/users:
post:
//some additional information here
responses:
'500':
//and for example here I want to add not only 201 status code but also others
description: >-
Something went wrong on back end
//however I have to do something like this (writing them all)
'502':
description: >-
Something went wrong on back end
//and so on..
What is best practices to overcome that? Maybe I have a bad point from the beginning.
You can use anchors and aliases:
path:
/users:
responses:
'500':
description: &desc1 >-
Something went wrong on back end
'502':
description: *desc1
OpenAPI 3.0 supports response ranges '1XX'-'5XX' that can be used instead of listing the codes individually:
responses:
'5XX':
description: Something went wrong on back end
If you still want to list the response codes individually but they have the same description and schema, you can $ref the common response definition like so:
responses:
'501':
$ref: '#/components/schemas/BackendErrorResponse'
'502':
$ref: '#/components/schemas/BackendErrorResponse'
components:
responses:
BackendErrorResponse:
description: Something went wrong on back end
content:
application/json:
schema:
...
There's also an enhancement request in the OpenAPI Specification repository to allow reusing description across different responses.
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).
There is a scenario for example as in any Application Controller while exposing a rest api we can make PathParams/UriParams as optional at controller level, so it wouldn't required always for client to pass it. Now I want to achieve same at RAML level. I can see their documentation that says like this.
"Although a URI parameter MAY be explicitly specified as optional, it
SHOULD be required when surrounded directly by slashes (/). In this
case, the URI parameter constitutes a complete URI path fragment, for
example .../{objectId}/.... It usually makes no sense to allow a URI
to contain adjacent slashes, enclosing no characters, for example,
...//.... Therefore, a URI parameter SHOULD be specified as optional
only when it appears adjacent to other text. For example,
/people/~{fieldSelectors} indicates that URI parameter
{fieldSelectors} can be blank, and therefore optional, which implies
that /people/~ is a valid relative URI."
That does give sense that we can try with combination of letter e,g /{someLetter}{uriParam} .. at end of resource Url. I did try this way but it always mention that "resouce not found"
Issue is just related to RAML configuration. for example this is sample resource url for which I have to add url param.
/test-api/{testId}
Now I want to keep it the client decision to either pass UriParameter or not.
This is sample RAML code I am trying.
/test-api/{testId}:
uriParameters:
testId?: string
/test-api/{testId}:
uriParameters:
testId: string
required: false
/test-api{testId}:
uriParameters:
testId: string
Now all three approaches aren't working.
1st approach simply making testId as optional using '?'. But if I skip UriParam it shows that no resource found for this.
2nd approach with required: false also not working looks like RAML is ignoring this validation it always expect even a single '/' from me after /test-api
3rd approach isn't working because it again expect me to put UriParam otherwise consider default one.
To subscribe to the automatic insertion of the URI parameter in RAML 1.0 make this change:
/test-api:
/{testId}:
uriParameters:
testId:
description: Id of test
type: string
required: false
get:
description: return test
responses:
200:
body:
application/json:
example: { "message": "success" }
put:
description: update test
responses:
200:
body:
application/json:
example: { "message": "success" }
delete:
description: remove test
responses:
200:
body:
application/json:
example: { "message": "success" }
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")
);
I am building my first RESTful API for practising and learning. I am using RAML and will realize it with MuleSofts AnypointStudio. I don't really know how to deal with responses, particularly, error responses. I managed to figure out which HTTP status codes I want for my responses but didn't manage to figure out how to handle the response messages.
Do I need to define response datatype and example message for every response code (200, 201, 204, 404 etc.)? If I can have one datatype and one example message, how do I do use them accordingly?
Currently, I have defined one error type and one example message.
Error.raml
#%RAML 1.0 DataType
type: object
description: This general error structure is used throughout this API.
properties:
code:
type: integer
minimum: 400
maximum: 599
description?:
type: string
default: "Bad query parameter [$size]: Invalid integer value [abc]"
example: The server understood the request, but is refusing to fulfill it
reasonPhrase?:
type: string
examples:
example: Bad Request
example1: Forbidden
example: !include ../examples/error_example.json
error_example.json
{
"code": 400,
"description": "Bad query parameter [$size]: Invalid integer value [abc]",
"reasonPhrase": "Bad Request"
}
As you can see, I have variables in both datatype and example message. They were generated by Restlet. I don't know how to utilise them yet so I just left them for the time being.
Would really appreciate any help and tips.
Do I need to define response datatype and example message for every response code (200, 201, 204, 404 etc.)? If I can have one datatype and one example message, how do I do use them accordingly?
No you don't. For a resource you could specify responses such as 200 or 404 (these are the most commonly used)
From the docs:
resourceTypes:
collection:
description: Collection of available songs in Jukebox
get:
description: Get a list of songs based on the song title.
responses:
200:
body:
application/json:
post:
description: |
Add a new song to Jukebox.
queryParameters:
access_token:
description: "The access token provided by the authentication application"
example: AABBCCDD
required: true
type: string
body:
application/json:
type: song
responses:
200:
body:
application/json:
example: |
{ "message": "The song has been properly entered" }
An example of a resource with a not found error:
collection-item:
description: Entity representing a <<resourcePathName|!singularize>>
get:
description: |
Get the <<resourcePathName|!singularize>>
with <<resourcePathName|!singularize>>Id =
{<<resourcePathName|!singularize>>Id}
responses:
200:
body:
application/json:
404:
body:
application/json:
example: |
{"message": "<<resourcePathName|!singularize>> not found" }
There's an excellent blog post about this. Have a look at RAML tutorials as they have nice docs.
You could also have a look at Swagger for more "inspiration".
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!