I am currently writing a documentation for an api which returns a json or a pdf (binary) based on the Accept-Header sent to the system.
How can I specify that the response is of type binary or similar?
In the RAML Spec I found the type: file which seems to be what I was looking for. See https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md#file
You will need to define the possible responses as below.
responses:
200:
body:
application/octet-stream:
.......
application/json:
........
In addition, you can also specify ACCEPT header with the enum of possible content types.
headers:
Accept:
type: string
enum: [application/octet-stream, application/json]
required: true
Related
Our API returns various response codes. For some response codes 4xx and above, a body may be returned. For example, an HTTP response code of 400 may be returned in several different cases described in the business logic, in some cases the response may contain a body, and in some cases the body may be completely absent.
My question is - how can I describe in the specification a situation where, for the same HTTP response code, for example, for HTTP 400, the API can return a response body or there can be no response body at all?
Addition. I am trying to describe the HTTP response code for the same endpoint.
Examples:
The response contains a body:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: some_ref_here
examples:
example-1:
value:
message:
title: This email address cannot be used
detail: Use a different email address.
severity: error
headers:
Content-Type:
schema:
type: string
description: Some description.
Cache-Control:
schema:
type: string
description: Some description.
Pragma:
schema:
type: string
description: Some description.
The response does not contain a body:
'400':
description: Bad Request
headers:
Content-Type:
schema:
type: string
description: Some description.
Cache-Control:
schema:
type: string
description: Some description.
Pragma:
schema:
type: string
description: Some description.
I'm trying to specify for a 400 HTTP code that it can either contain content, or content can be completely absent.
That's the default. If the responses 'content' field is absent, it won't be validated against the provided response.
On the other hand, if you want to indicate that a response body must be present, you can do that indirectly by checking for a non-empty Content-Length or Content-Type header.
I would like to download a PDF file using a nodejs lambda function deployed in AWS. Please let me know the configurations to be provided in serverless settings.yaml file.
I am able to download PDF by making below configuration changes from console.
1) Add Content-Type as application/pdf 2) Map the response model for application/pdf=>Empty 3) Change the content handling in integration response from passthrough (default) to Convert to Binary. I am looking for options where these can be provided in serverless configuration file
I am looking for options where content handling and response model can be set using serverless
Below is the snippet from serverless.yml
events:
- http:
path: /test
method: get
integration: lambda
response:
statusCodes:
200:
pattern: '' # Default response method
headers:
Content-Type: "'application/pdf'"
In your lambda function, you have to return a json object like that:
{
statusCode: 200,
headers: { 'Content-Type': 'application/pdf' },
body: YOUR_PDF_base64_encoded_string,
isBase64Encoded: true, // important
};
then, you can use serverless-apigw-binary plugin to config APIGateway Binary Support or you can do it by manualy: Change APIGateway setting
use application/pdf instead of my image mime types.
I have a swagger.yaml something like this:
swagger: "2.0"
paths:
/something:
get:
parameters:
- name: format
in: query
type: string
pattern: '^(csv|json|xml)$'
responses:
200:
schema:
type: ?
And I want to return different formats (csv, json, xml) depending on the value of the format query parameter (eg. localhost/api/something?format=csv).
How can I specify the different response formats in the spec?
I found a workaround, by providing different endpoints:
swagger: "2.0"
paths:
/something/json:
get:
produces:
- application/json
responses:
200:
schema:
type: object
properties:
...
/something/csv:
get:
produces:
- text/csv
responses:
200:
schema:
type: string
Note the different produces: inside each get, and none at the top level.
The actual response header for the csv endpoint is:
Content-Length:64
Content-Type:text/csv; charset=utf-8
Date:Fri, 26 Aug 2016
I have also tried adding headers to the yaml (straight after the code above), but it doesn't change the actual response header:
headers:
Content-type:
type: string
description: text/csv; charset=utf-8
Content-Disposition:
type: string
description: attachment; filename=data.csv
At either endpoint I get a console message (I am building this using connexion):
Resource interpreted as Document but transferred with MIME type application/json, or
Resource interpreted as Document but transferred with MIME type text/csv
Also, the csv is interpreted as a file to download, not displayed in the browser.
...so I suspect I haven't quite got it right yet.
I am loving how RAML can dynamically reference different schemas when declaring a resourceType like:
resourceTypes:
- collection:
get:
responses:
200:
body:
application/json:
schema: <<schema>>
post:
body:
application/json:
schema: <<schema>>Create
responses:
200:
body:
application/json:
schema: <<schema>>
Here I am able to use this like
/users:
type: { collection: { schema: user } }
and RAML will give me user schema responses from GETs and POSTs and also use the userCreate schema for sending POST requests. Cool! Now I can reuse my collection definition with tons of different schemas.
But now that I want to have example json for everything too, I was hoping to utilize the <<schema>> var in another way to leverage "code reuse". I was hoping to be able to do
resourceTypes:
- collection:
get:
responses:
200:
body:
application/json:
schema: <<schema>>
example: examples/v1-<<schema>>.json
post:
body:
application/json:
schema: <<schema>>Create
example: examples/v1-<<schema>>-create.json
responses:
200:
body:
application/json:
schema: <<schema>>
example: examples/v1-<<schema>>.json
but unfortunately this does not work. I get an error saying
error: File with path "/examples/v1-%3C%3Cschema%3E%3E.json" does not exist
So now I have resorted to manually adding this to all my collections and the /users example above has become
/users:
type: { collection: { schema: user } }
get:
responses:
200:
body:
application/json:
example: !include examples/v1-user.json
post:
body:
application/json:
example: !include examples/v1-user-create.json
responses:
200:
body:
application/json:
example: !include examples/v1-user.json
To me, this is a LOT of overhead just to add examples. Especially when I want to repeat the pattern over many resources.
The question: Is there a way to accomplish this?
No, this is not allowed in RAML 0.8 according to the spec. It might be allowed in future versions though.
Since RAML is just a standard, I first would ask: Who/What is throwing that error? (I mean, what tool are you using?)
Plus: Are you sure about the example (the first one)? It's not using !include, so, should not be even intending to reach that inexistent file (I'm assumed that you are using !includes in your original script but omitted that when copying here).
Additionally, and I know you are not asking for this, but just in case:
- You could pass 2 parameters (as a workaround), one for the schema and another for the example (it's still overhead but not THAT hardcoded).
- Do you know about the reserved parameters? Using that + "singularize" or "pluralize" depending the case, could also help you in your reuse enterprise ;) Take a look at http://raml.org/docs-200.html#parameters
I’d like to annotate some error responses, like so:
* Response 412
If the Etag supplied in `If-Match` didn’t match.
* Response 428
If the request didn’t include the header `If-Match`.
but the parser (snowcrash) seems to be interpreting the annotations as response bodies.
How can I annotate these responses and have snowcrash understand that they’re annotations?
I figured it out: I need to add an empty Body section to the response, like so:
* Response 204
The request succeeded; there’s no need to transfer a representation of the new state of the resource, as the resource no longer exists.
* Body
* Response 412
If the Etag supplied in `If-Match` didn’t match.
* Body
This is then parsed as desired:
responses:
- name: 204
description: "The request succeeded; there’s no need to transfer a representation of the new state of the resource, as the resource no longer exists.\n"
headers:
body:
schema:
- name: 412
description: "If the Etag supplied in `If-Match` didn’t match.\n"
headers:
body:
schema:
- name: 428
description: "If the request didn’t include the header `If-Match`.\n"
headers:
body:
schema: