This question already has answers here:
In OpenAPI 3, how to document that an Accept header with a specified value is necessary on request in order for a successful API call?
(2 answers)
Closed 1 year ago.
I am trying to write a Open API Specification(V3) for a API that i am developing and facing issue in defining the accept header. In my spec, defining the accept header as follows:
parameters:
- in: header
name: Accept
required: true
description: Defines the media type and version of the API endpoint
schema:
enum:
- 'application/vnd.iotdeviceenrollment.v1'
- 'application/json'
type: string
But i found out that i have used a restricted value 'Accept' as the name of a header parameter:
https://apisecurity.io/encyclopedia/content/oasv3/oasconformance/bestpractices/v3-warning-parameter-header-accept
As a result of this, when i export the Open API Specification to the Azure APIM, the accept header is not visible and being ignored.
If this is the case, what is the correct way to define an accept header in the Open API Specification V3
Note: When tested with Open API SwaggerUI, i could see the accept header value in the UI preview.
You do not need to define the Accept header manually. The values are derived from the keys of your mediatypeObjects.
Related
My spec is as below.
/path:
/user:
get:
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
Problem is that it is giving me the below warning. I get the same warning if I add Content-Type or Accept header.
Header parameters named Authorization are ignored. Use securitySchemes and security to define the Authorization
I tried the below but I don't see Authorization header added in the request. I am using https://editor.swagger.io to create the spec.
/path:
/user:
get:
parameters:
- name: Authorization
in: header
required: true
schema:
type: string
security:
- my_auth: []
components:
securitySchemes:
my_auth:
type: http
scheme: bearer
bearerFormat: JWT
Any help is appreciated. Thanks !!
In the request parameters, there are operation's specific parameters.
The general purpose HTTP headers aren't defined here because:
Content-Type is defined by the request body content. If there are multiple content types, the consumer has to choose and set Content-Type accordingly.
Accept is similar; it only relates to the response message.
For security, we do not describe the Authorization header but instead define the security scheme (see docs for more).
You may use the description property to explain how to use these headers with your API. However, if your API follows standards, it should not be necessary.
Once you have added the security schema to your API definition, you can use the Authorization function of Swagger Editor. So, you will add your token and trigger "Try it out." Swagger will populate the Authorization header; see the attached screenshot.
I am using OpenAPI (Swagger) to define a web service.
In the response section, I define the following code explicitly
responses:
'200':
description: Your order has been placed
content: ...
However, when I call the service, it returns "200 OK", which is a standard http status code description instead of the description I define explicitly
According to here https://swagger.io/docs/specification/describing-responses/, it says "If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code."
Do I miss/misunderstand something?
The description field in the OpenAPI definition is metadata used for documentation purposes only.
This description is not related to the status text (aka reason-phrase) value in HTTP responses, such as "OK" in "HTTP/1.1 200 OK". Most servers/frameworks use common status text e.g. "200 OK" or "403 Forbidden".
I am facing fellow two problems related to Swagger open API
I am not able to pass custom header through swagger open API while calling my API, please suggest how can we pass custom header, through swagger open API.
When I added POI dependency on my project's pom.xml, it stopped working through swagger open API, however, it is working with the postman, please suggest what could be the issue.
From Describing Parameters:
An API call may require that custom headers be sent with an HTTP request. OpenAPI lets you define custom request headers as in: header parameters. For example, suppose, a call to GET /ping requires the X-Request-ID header:
GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac
Using OpenAPI 3.0, you would define this operation as follows:
paths:
/ping:
get:
summary: Checks if the server is alive
parameters:
- in: header
name: X-Request-ID
schema:
type: string
format: uuid
required: true
How can I get the equivalent of php:
$_SERVER['HTTP_ORIGIN']
in delphi?, I'm using TWebRequest in a WebBroker applications project (not datasnap).
It works using Request.GetFieldByName ('ORIGIN') where Request is some instance of TWebReques. However, there are "hidden" headers, to obtain them you can use a solution based on the response of the following link: Enumerate TWebRequest HTTP header fields, and save them in a TDictionary
I use AFHTTPRequestOperationManager to send HTTP request, and have some information put in the HTTP custom header, named "X-AKey".
I confirmed the header name by:
NSLog(#"%#", manager.requestSerializer.HTTPRequestHeaders);
Then, I captured the outgoing message, and found that the header name has changed to "HTTP_X_AKEY".
I've searched some questions, and found that this might be a standard way of naming custom header: "Meta-variables with names beginning with "HTTP_" contain values read from the client request header fields, if the protocol used is HTTP. The HTTP header field name is converted to upper case, has all occurrences of "-" replaced with "" and has "HTTP" prepended to give the meta-variable name."
Nevertheless, my question is: CAN I send a message with a custom header name exactly as I specified? That is, in my case, "X-AKey" instead of "HTTP_X_AKEY"?
(PS: For real applications, if both the client and server are negotiated to use the 'HTTP_xxx' format, there won't be any problem. I'm just curious about the answer for now.)
Thanks.
Try this:
[manager.requestSerializer setValue:#"SomeValue" forHTTPHeaderField:#"SomeHeaderField"]