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.
Related
I have an api generated through go-swagger. I am trying to put in a session check it is not firing as I expected. I followed an example that I found in github but didn't seem to work for me.
My code:
// Applies when the "X-Session-Key" header is set
api.SessionKeyHeaderAuth = func(token string) (interface{}, error) {
// test the token
success := routeHandler.HandleSessionHeaderKey(token)
if success{
return nil, nil
}
//We are pessimistic, if they aren't successful then we return a 401
api.Logger("Access attempt with incorrect api key auth: %s", token)
return nil, errors.New(401, "incorrect api key auth")
}
My Yaml (for the endpoint that I am curling):
/auth/logout:
post:
summary: Logs in the user
consumes:
- application/x-www-form-urlencoded
operationId: authLogoutUser
tags:
- auth
description:
Allow users to log out and their session will be terminated
produces:
- application/json
parameters:
- in: header
name: X-Session-Key
type: string
required: true
- in: header
name: X-Profile-Key
type: string
required: true
responses:
200:
description: Login Success
headers:
ProfileKeyHeader:
type: string
description: The key for the profile data
SessionKeyHeader:
type: string
description: The key for the session data
400:
description: Whether the user is not found or error while login, decided on a generic login failure error
schema:
$ref: 'definitions.yaml#/definitions/Error'
429:
description: Too many requests and being throttled
schema:
$ref: 'definitions.yaml#/definitions/Error'
500:
description: Too many requests and being throttled
schema:
$ref: 'definitions.yaml#/definitions/Error'
Any help to see what I did incorrectly would be appreciated.
So, I was being an idiot...
The issue was that I forgot to add Security to my swagger yaml. Once I did that then my function was getting called.
operationId: authLogoutUser
tags:
- auth
description:
Allow users to log out and their session will be terminated
produces:
- application/json
security:
- SessionKeyHeader: []
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
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’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:
I have a jqGrid edit form that contains a date field. I want to implement exception handling so that error messages from the server will be displayed in the edit form. Example response:
HTTP/1.1 400 Bad Request
Server: Apache-Coyote/1.1
Date: Fri, 28 Jun 2013 15:47:21 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: close
11
"Bad Date format"
0
jqGrid only displays "error status:'Bad Request' Error Code: 400", at the top of the form. How can I have it also display the error message: "Bad Date format" ?
You should use errorTextFormat callback of form editing. As the parameter the callback get jqXHR object which is wrapper on XMLHTTPRequest object. It's responseText property represent the body of the response (11\n"Bad Date format"\n0 in your case). The status property gets you the HTTP status code (400 in your example). You can use getResponseHeader and getAllResponseHeaders to examine all HTTP headers.
By the way I find very strange that the response contains Content-Type: application/json, but the body of the response don't contains JSON string.
Assume that your response contains 2 fields: status (OK, ERROR,..) and message then you should write a function like this:
validateAfterSubmit = function(response, postdata){
var json = response.responseText; // response text is returned from server.
var result = JSON.parse(json); // convert json object into javascript object.
return [result.status == 'OK', result.message, null];
};
and specify in the edit/add options:
//edit options
{ url: '...',
afterSubmit: validateAfterSubmit
},
//add options
{ url: '...',
afterSubmit: validateAfterSubmit
},
hopefully this can help