How Response Headers can be set in NSwag?
I tried to add to OpenApiResponse.Headers collection.
var headerSchema = new JsonSchema()
{
Type = JsonObjectType.String,
Description = "headerDescription"
};
response.Headers["headerName"] = headerSchema;
Unfortunately, the generated json is not correct though. According to Swagger website, the output of response header should be like this:
paths:
/ping:
get:
summary: Checks if the server is alive.
responses:
'200':
description: OK
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Request limit per hour.
X-RateLimit-Remaining:
schema:
type: integer
description: The number of requests left for the time window.
X-RateLimit-Reset:
schema:
type: string
format: date-time
description: The UTC date/time at which the current rate limit window resets.
Can we achieve this using Nswag?
Related
i am learning how to deploy swagger and openAPI.
i have a url as follows:
http://127.0.0.1:5000/getDistance/12.496366,41.902782,-3.606997572,40.47416477
the user enters the coordinates and i receive response in a form of json file then i get the distance from the json file.
in swagger i have the below posted code and i would like to add
response body
i read about but i can not still figure it out
code:
parameters:
- name: startAndEndCoords
in: path
description: Start and end GPS coordinates as comma separated values in terms of longitude and latitude respectively.
required: true
schema:
type: number
format: float
allowEmptyValue: false
requestBody:
responses:
'200':
description: OK. Successful operation
If we follow the OAS3 spec for Response here we can see that each response status code can have multiple media types and each media type in turn has a schema particular to it.
UseCase : For example oas3 example below, we can see 200 has a binary stream response but 400 has 3 media-types:application/json, application/xml, text/plain.
So is the client expected to request accept-type header with all the media-types mentioned below. How can we have specific media-type for 400 response code, or basically how we can convey to the REST Service to respond with media type as application/xml when its a 400 bad request and if 200 is returning a binary stream.
Does this OAS3 response multiple media-type make sense for Client/Server Errors. If yes then whats the accept-type set for expecting, say "application/xml" for 400 bad request.
Please refer the below swagger UI snap. Where we see a drop-down for the media-types for error code as well. But when we try out executing the rest operations, the accept header is only populated as per the 200 status code's media-type
openapi: 3.0.0
info:
version: "1.0"
title: Resource
description: Resource service
paths:
/resource:
get:
summary: getResource
description: getResource
operationId: get-resource
responses:
"200":
description: a binary document to be returned
content:
application/octet-stream:
schema:
type: string
format: binary
"400":
description: Bad Request
content:
application/json:
schema:
$ref: "#/components/schemas/Error400Element"
application/xml:
schema:
$ref: "#/components/schemas/Error400Element"
text/plain:
schema:
$ref: "#/components/schemas/Error400Element"
"500":
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error500Element"
application/xml:
schema:
$ref: "#/components/schemas/Error500Element"
text/plain:
schema:
$ref: "#/components/schemas/Error500Element"
servers:
- url: http://localhost:8088/
components:
schemas:
Error400Element:
type: object
required:
- name
properties:
name:
type: string
number:
type: integer
Error500Element:
type: object
properties:
number:
type: integer
flag:
type: boolean
EDIT : modified the OAS3 spec and the SwaggerUI
I'm writing an OpenAPI spec for an existing API. This API returns status 200 for both success and failure, but with a different response structure.
For example, in the signup API, if the user signed up successfully, the API sends status 200 with the following JSON:
{
"result": true,
"token": RANDOM_STRING
}
And if there is a duplicated user, the API also sends status 200, but with the following JSON:
{
"result": false,
"errorCode": "00002", // this code is duplicated error
"errorMsg": "duplicated account already exist"
}
In this case, how to define the response?
This is possible in OpenAPI 3.0 but not in 2.0.
OpenAPI 3.0 supports oneOf for specifying alternate schemas for the response. You can also add multiple response examples, such as successful and failed responses. Swagger UI supports multiple examples since v. 3.23.0.
openapi: 3.0.0
...
paths:
/something:
get:
responses:
'200':
description: Result
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiResultOk'
- $ref: '#/components/schemas/ApiResultError'
examples:
success:
summary: Example of a successful response
value:
result: true
token: abcde12345
error:
summary: Example of an error response
value:
result: false
errorCode: "00002"
errorMsg: "duplicated account already exist"
components:
schemas:
ApiResultOk:
type: object
properties:
result:
type: boolean
enum: [true]
token:
type: string
required:
- result
- token
ApiResultError:
type: object
properties:
result:
type: boolean
enum: [false]
errorCode:
type: string
example: "00002"
errorMsg:
type: string
example: "duplicated account already exist"
In OpenAPI/Swagger 2.0, you can only use a single schema per response code, so the most you can do is define the varying fields as optional and document their usage in the model description or operation description.
swagger: "2.0"
...
definitions:
ApiResult:
type: object
properties:
result:
type: boolean
token:
type: string
errorCode:
type: string
errorMsg:
type: string
required:
- result
I'm using Swagger Editor to document an existing API, built in Node, but it keeps giving me the following error:
Schema error at paths./upload/Rate.post.parameters[0]
is not exactly one from <#/definitions/parameter>,<#/definitions/jsonReference>
This error appears in 3 places of my code:
paths./upload/Rate.post.parameters[0]
paths./upload/Rate.post.parameters[1]
paths./users/register.post.parameters[0]
I've searched quite a bit, but, for example, this link did not solved my problem although it's the same error:
Swagger parameter error "is not exactly one from <#/definitions/parameter>"?
Here is my Swagger definition:
/users/register:
post:
tags:
- "users"
description: Allows an user to register at the Server
produces:
- application/json
parameters:
- name: body
in: body
description: JSON Object with information for a Register request from an User
schema:
type: object
required:
- username
- password
- weight
- height
- gender
- restRate
- age
properties:
username:
type: string
password:
type:
format: password
weight:
type: integer
height:
type: integer
gender:
type: string
restRate:
type: integer
age:
type: integer
# Expected responses for this operation:
responses:
# Response code
200:
description: Register successful
schema:
type: string
/upload/Rate:
post:
tags:
- "upload"
description: Allows an user to upload a file into the server
produces:
- application/json
consumes:
- multipart/form-data
parameters:
- name: body
in: formData
description: JSON Object with information for an upload request from an User
required: false
schema:
type: object
required:
- user
- overlap
- window
- latitude
- longitude
- time
- date
properties:
user:
type: string
overlap:
type: string
window:
type: string
latitude:
type: string
longitude:
type: string
time:
type: string
date:
type: string
- name: files
in: formData
description: File with the corresponding Rate
required: false
schema:
type: object
required:
- rate
properties:
rate:
type: file
# Expected responses for this operation:
responses:
# Response code
200:
description: Login successful
schema:
type: string
Maybe this will help, but the post route (upload/Rate) should receive a request that will be something like this, once I've parsed its parameters:
user = req.body.user;
rr = req.files.rate;
overlap = req.body.overlap;
windowT = req.body.window;
latitude = req.body.latitude;
longitude = req.body.longitude;
time = req.body.time;
date = req.body.date;
Thank you for your help and time!
There are multiple issues.
/upload/register:
Schema property password is missing the value for type.
Property name mismatch - restHR (under properties) vs restRate (in the required list).
upload/Rate:
The problem here is caused by object parameters in a multipart/form-data request. In OpenAPI (fka Swagger) 2.0, form parameters can be primitive values and arrays, but not objects. So your example cannot be described using OpenAPI 2.0.
If you were designing a new API (or if you could and were willing to change the API implementation to be compatible with OpenAPI 2.0), possible solutions would be:
Change the operation to consume application/json and combine all input parameters into a single JSON object. The file parameter would need to be implemented as a base64 string - type: string with format: byte.
Use multipart/form-data but split object parameters into individual form parameters.
The upcoming OpenAPI 3.0 will support object parameters in form data:
https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#special-considerations-for-multipart-content
I'm preparing my API documentation by doing it per hand and not auto generated. There I have headers that should be sent to all APIs and don't know if it is possible to define parameters globally for the whole API or not?
Some of these headers are static and some has to be set when call to API is made, but they are all the same in all APIs, I don't want to copy and paste parameters for each API and each method as this will not be maintainable in the future.
I saw the static headers by API definition but there is no single document for how somebody can set them or use them.
Is this possible at all or not?
It depends on what kind of parameters they are.
The examples below are in YAML (for readability), but you can use http://www.json2yaml.com to convert them to JSON.
Security-related parameters: Authorization header, API keys, etc.
Parameters used for authentication and authorization, such as the Authorization header, API key, pair of API keys, etc. should be defined as security schemes rather than parameters.
In your example, the X-ACCOUNT looks like an API key, so you can use:
swagger: "2.0"
...
securityDefinitions:
accountId:
type: apiKey
in: header
name: X-ACCOUNT
description: All requests must include the `X-ACCOUNT` header containing your account ID.
# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
- accountId: []
or in OpenAPI 3.0:
openapi: 3.0.0
...
components:
securitySchemes:
accountId:
type: apiKey
in: header
name: X-ACCOUNT
description: All requests must include the `X-ACCOUNT` header containing your account ID.
# Apply the "X-ACCOUNT" header globally to all paths and operations
security:
- accountId: []
Tools may handle security schemes parameters differently than generic parameters. For example, Swagger UI won't list API keys among operation parameters; instead, it will display the "Authorize" button where your users can enter their API key.
Generic parameters: offset, limit, resource IDs, etc.
OpenAPI 2.0 and 3.0 do not have a concept of global parameters. There are existing feature requests:
Allow for responses and parameters shared across all endpoints
Group multiple parameter definitions for better maintainability
The most you can do is define these parameters in the global parameters section (in OpenAPI 2.0) or the components/parameters section (in OpenAPI 3.0) and then $ref all parameters explicitly in each operation. The drawback is that you need to duplicate the $refs in each operation.
swagger: "2.0"
...
paths:
/users:
get:
parameters:
- $ref: '#/parameters/offset'
- $ref: '#/parameters/limit'
...
/organizations:
get:
parameters:
- $ref: '#/parameters/offset'
- $ref: '#/parameters/limit'
...
parameters:
offset:
in: query
name: offset
type: integer
minimum: 0
limit:
in: query
name: limit
type: integer
minimum: 1
maximum: 50
To reduce code duplication somewhat, parameters that apply to all operations on a path can be defined on the path level rather than inside operations.
paths:
/foo:
# These parameters apply to both GET and POST
parameters:
- $ref: '#/parameters/some_param'
- $ref: '#/parameters/another_param'
get:
...
post:
...
If you're talking about header parameters sent by consumer when calling the API...
You can at least define them once and for all in parameters sections then only reference them when needed.
In the example below:
CommonPathParameterHeader, ReusableParameterHeader and AnotherReusableParameterHeader are defined once and for all in parameterson the root of the document and can be used in any parameters list
CommonPathParameterHeaderis referenced in parameters section of /resources and /other-resources paths, meaning that ALL operation of these paths need this header
ReusableParameterHeader is referenced in get /resources meaning that it's needed on this operation
Same thing for AnotherReusableParameterHeader in get /other-resources
Example:
swagger: '2.0'
info:
version: 1.0.0
title: Header API
description: A simple API to learn how you can define headers
parameters:
CommonPathParameterHeader:
name: COMMON-PARAMETER-HEADER
type: string
in: header
required: true
ReusableParameterHeader:
name: REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
AnotherReusableParameterHeader:
name: ANOTHER-REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
paths:
/resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/ReusableParameterHeader'
responses:
'200':
description: gets some resources
/other-resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/AnotherReusableParameterHeader'
responses:
'200':
description: gets some other resources
post:
responses:
'204':
description: Succesfully created.
If you're talking about header sent with each API response...
Unfortunately you cannot define reusable response headers.
But at least you can define a reusable response containing these headers for common HTTP responses such as a 500 error.
Example:
swagger: '2.0'
info:
version: 1.0.0
title: Header API
description: A simple API to learn how you can define headers
parameters:
CommonPathParameterHeader:
name: COMMON-PARAMETER-HEADER
type: string
in: header
required: true
ReusableParameterHeader:
name: REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
AnotherReusableParameterHeader:
name: ANOTHER-REUSABLE-PARAMETER-HEADER
type: string
in: header
required: true
paths:
/resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/ReusableParameterHeader'
responses:
'200':
description: gets some resources
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
/other-resources:
parameters:
- $ref: '#/parameters/CommonPathParameterHeader'
get:
parameters:
- $ref: '#/parameters/AnotherReusableParameterHeader'
responses:
'200':
description: gets some other resources
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
post:
responses:
'204':
description: Succesfully created.
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
'500':
$ref: '#/responses/Standard500ErrorResponse'
responses:
Standard500ErrorResponse:
description: An unexpected error occured.
headers:
X-Rate-Limit-Remaining:
type: integer
X-Rate-Limit-Reset:
type: string
format: date-time
About OpenAPI (fka. Swagger) Next version
The OpenAPI spec (fka. Swagger) will evolve and include the definition of reusable response headers among other things (cf. https://github.com/OAI/OpenAPI-Specification/issues/563).
As per this Swagger issue comment, support for global parameters (including header parameters) is not planned in foreseeable future, but to limit the repetition you should use parameters references as in #Arnaud's answer (parameters: - $ref: '#/parameters/paramX').
also wish some global variables, can be used anywhere.
( even in some examples, so can change common settings globally in ui ).
something like
"hello ${var1}" in shell or javascript.
searched docs many times, not found solution yet.
: (