In OpenAPI (Swagger) 2.0, we could define header parameters like so:
paths:
/post:
post:
parameters:
- in: header
name: X-username
But in OpenAPI 3.0.0, parameters are replaced by request bodies, and I cannot find a way to define header parameters, which would further be used for authentication.
What is the correct way to define request headers in OpenAPI 3.0.0?
In OpenAPI 3.0, header parameters are defined in the same way as in OpenAPI 2.0, except the type has been replaced with schema:
paths:
/post:
post:
parameters:
- in: header
name: X-username
schema:
type: string
When in doubt, check out the Describing Parameters guide.
But in Swagger 3.0.0 parameters are replaced by request bodies.
This is only true for form and body parameters. Other parameter types (path, query, header) are still defined as parameters.
define header parameters, which would further be used for authentication.
A better way to define authentication-related parameters is to use securitySchemes rather than define these parameters explicitly in parameters. Security schemes are used for parameters such as API keys, app ID/secret, etc. In your case:
components:
securitySchemes:
usernameHeader:
type: apiKey
in: header
name: X-Username
paths:
/post:
post:
security:
- usernameHeader: []
...
Related
I have multiple paths that require an id number. There are some paths where multiple ids are required.
I know that I can reference a parameter when building a path.
paths:
/path1/{path1ID}
parameters:
- $ref: '#/components/parameters/path1ID_param'
components:
parameters:
path1ID_param:
name: path1ID
in: path
schema:
type: integer
If I do it this way, I'm going to have a lot of repeated definitions where the only change is the name. This grates.
Is there a way I can override the name in the path definition? I have tried variations of allOf but haven't hit on anything yet. I've searched the swagger documentation without much luck. I've searched here and found a lot of interesting pointers that helped me refine my API ... but I found nothing related to what I'm trying to do.
Is it possible to do something like this?
paths:
/path1/{path1ID}
parameters:
- $ref: '#/components/parameters/parmID_param/'
- name: path1ID
/path1/{path1ID}/subpath2/{subpath2ID}
- $ref: '#/components/parameters/parmID_param/'
- name: path1ID
- $ref: '#/components/parameters/parmID_param/'
- name: subpath2ID
components:
parameters:
path1ID_param:
name: path1ID
in: path
schema:
type: integer
This is not supported.
As of OpenAPI 3.1, you can only override the description of a referenced parameter, but not its name or other attributes (required, style, etc.).
Here are existing feature requests in the OpenAPI Specification repository:
Extend/override properties of a parameter
Allow required as sibling of $ref (like summary/description)
Is there any way to document the following query?
GET api/v1/users?name1=value1&name2=value
where the query parameter names are dynamic and will be received from the client.
I'm using the latest Swagger API.
Free-form query parameters can be described using OpenAPI 3.x, but not OpenAPI 2.0 (Swagger 2.0). The parameter must have type: object with the serialization method style: form and explode: true. The object will be serialized as ?prop1=value1&prop2=value2&..., where individual prop=value pairs are the object properties.
openapi: 3.0.3
...
paths:
/users:
get:
parameters:
- in: query
# Arbitrary name. It won't appear in the request URL, but will be used
# in server & client code generated from this OAS document.
name: params
schema:
type: object
# If the parameter values are of specific type, e.g. string:
additionalProperties:
type: string
# If the parameter values can be of different types
# (e.g. string, number, boolean, ...)
# additionalProperties: true
# `style: form` and `explode: true` is the default serialization method
# for query parameters, so these keywords can be omitted
style: form
explode: true
Free-form query parameters are supported in Swagger UI 3.15.0+ and Swagger Editor 3.5.6+. In the parameter editor, enter the parameter names and values in the JSON object format, e.g. { "prop1": "value1", "prop2": "value2" }. "Try it out" will send them as param=value query parameters:
Not sure about Codegen support though.
#Helen's answer works perfectly even with Spring using the springdoc-openapi-ui library.
Dependency:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.1.43</version>
</dependency>
In the API function, add the following parameter:
#Parameter(in=ParameterIn.QUERY,
name="params", style=ParameterStyle.FORM,
schema=#Schema(type="object"), explode=Explode.TRUE,
example="") String paramsObj
Our business is looking to create a Swagger document to represent an internal server.
For various reasons, each request is required to include a series of extraneous header parameters:
parameters:
- name: device_id
in: header
required: false
type: string
- name: ip_address
in: header
required: true
type: string
- name: client_id
in: header
required: true
type: string
- name: request_id
in: header
required: true
type: string
The server will reject the request if the parameters are not included but the parameters themselves are unrelated to the request being made.
The primary purpose of the Swagger document is to generate a small number of client applications (all of which we control) to interact with the server.
We could add each parameter explicitly on every request but this would result in repetition within the document and additional handling within the clients. Alternatively, we could regard these parameters as metadata and exclude them from the document, relying on the clients to add them to each request appropriately.
Is there a recommended approach for such parameters?
An OpenAPI definition serves as a contract between the API provider and the clients. It can be used, among other things, to generate client SDKs. So it's expected that an OpenAPI definition describes your API precisely, including the request body format, required parameters, authentication, etc.
All required parameters should be defined explicitly.
To reduce the code duplication, you can define reusable parameters in the global parameters section (for OpenAPI 2.0) or components/parameters section (for OpenAPI 3.0), and then $ref them from individual paths or operations, as shown here:
Swagger/OpenAPI - use $ref to pass a reusable defined parameter
Note that there's currently no way to $ref a group of parameters. The corresponding feature requests are tracked here:
Group multiple parameter definitions for better maintainability
Global/common parameters (this one is closed for some reason, even though it's not implemented)
I am making an API with swagger and am trying to update the YAML to add regex pattern requirements to the parameters. Currently I am trying the following:
# getCPIStatesForCountry endpoint
/getCPIStatesForCountry:
# This is a HTTP operation
get:
# Describe this verb here. Note: you can use markdown
description: |
Returns a list of states for a given country
produces:
- application/json
# This is array of GET operation parameters:
parameters:
-
name: country_code
in: query
description: Code of desired country
required: true
type: string
pattern: "^[a-zA-Z]+$"
The Swagger UI, however, is letting me enter anything as valid input. Why is this?
Parameter validation against pattern is supported in Swagger UI 3.4.3 and later.
This question is not a duplicate of (Swagger - Specify Optional Object Property or Multiple Responses) because that OP was trying to return a 200 or a 400.
I have a GET with an optional parameter; e.g., GET /endpoint?selector=foo.
I want to return a 200 whose schema is different based on whether the parameter was passed, e.g.,:
GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah -> {200, schema_2}
In the yaml, I tried having two 200 codes, but the viewer squashes them down as if I only specified one.
Is there a way to do this?
Edit: the following seems related: https://github.com/OAI/OpenAPI-Specification/issues/270
OpenAPI 2.0
OAS2 does not support multiple response schemas per status code. You can only have a single schema, for example, a free-form object (type: object without properties).
OpenAPI 3.x
In OAS3 you can use oneOf to define multiple possible request bodies or response bodies for the same operation:
openapi: 3.0.0
...
paths:
/path:
get:
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseOne'
- $ref: '#/components/schemas/ResponseTwo'
However, it's not possible to map specific response schemas to specific parameter values. You'll need to document these specifics verbally in the description of the response, operation and/or parameter.
Here's a possibly related enhancement request:
Allow operationObject overloading with get-^ post-^ etc
Note for Swagger UI users: Older versions of Swagger UI (before v. 3.39.0) do not automatically generate examples for oneOf and anyOf schemas. As a workaround, you can specify a response example or examples manually. Note that using multiple examples require Swagger UI 3.23.0+ or Swagger Editor 3.6.31+.
responses:
'200':
description: Success
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResponseOne'
- $ref: '#/components/schemas/ResponseTwo'
example: # <--- Workaround for Swagger UI < 3.39.0
foo: bar
I wanted the same thing, and I came up with a workaround that seems to work:
I´ve just defined two different paths:
/path:
(...)
responses:
200:
description: Sucesso
schema:
$ref: '#/definitions/ResponseOne'
(...)
/path?parameter=value:
(...)
responses:
200:
description: Sucesso
schema:
$ref: '#/definitions/ResponseTwo'
(...)
Paths do work on swagger editor. I can even document each option differently and put optional parameters that only may be on the second case toguether, making the API doc much cleaner. Using operationId you may generate cleaner names for the generated API methods.
I´ve posted the same solution here (https://github.com/OAI/OpenAPI-Specification/issues/270) to verify if I am missing something more.
I do understand it is not explicitly allowed/encouraged to do it (neither I found some place explicitly disallowing it). But as a workaround, and being the only way to document an API with this behaviour in the current specification,, looks like an option.
Two problems I´ve found out with it:
Java code gen URL escapes the "=" sign, therefore it wont work unless
you fix this in the generated code. Probably it happens in other code
generators.
If you have more query params it will add an extra "?" and fail;
If those are not blockers, it at least will allow you to document properly such cases and allow testing with swagger editor.