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.
Related
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
I wrote a swagger specification Yaml file and in the components section I have:
examples:
companyExample:
company:
id: uNiquEiD
name: Company Name
I use this companyExample in the response as following:
example:
$ref: '#/components/examples/companyExample'
Here is the output:
So what is this extra "$$ref": "#/components/examples/companyExample" is it a bug? How can I remove it?
The example keyword (not to be confused with multiple exampleS) does not support $ref. The whole example value must be specified inline:
example:
company:
id: uNiquEiD
name: Company Name
To $ref an example defined in #/components/examples, you'll need to use the examples keyword. examples can be used in parameters, request bodies, response bodies and response headers but NOT in schemas. In other words, examples can be used
alongside schema but not inside schema.
For instance, to $ref an example as a response example, you would use the following. Note that the example definition uses the value keyword to wrap the actual example value. (The example definition in your original question is not valid because of the missing value.)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
examples:
companyExample:
$ref: '#/components/examples/companyExample'
components:
examples:
companyExample:
summary: Sample company data
value:
# The actual example value begins here
company:
id: uNiquEiD
name: Company Name
Note for Swagger UI users: Support for multiple examples is available in Swagger UI 3.23.0+ and Swagger Editor 3.6.31+.
I'm writing a Swagger specification for an future public API that requires a very detailed and clean documentation. Is there a way to reference/link/point to another endpoint at some other location in the swagger.yml file?
For example, here is what I am trying to achieve:
paths:
/my/endpoint:
post:
tags:
- Some tag
summary: Do things
description: >
This endpoint does things.
See /my/otherEndpoint for stuff # Here I would like to have some kind of hyperlink
operationId: doThings
consumes:
- application/json
produces:
- application/json
parameters:
...
responses:
...
/my/otherEndpoint: # This is the endpoint to be referenced to
get:
...
I have found that $ref does not help because it simply replaces itself with the contents of the reference.
Can Swagger do such a thing?
Swagger UI provides permalinks for tags and operations if it's configured with the deepLinking: true option. These permalinks are generated based on the tag names and operationId (or if there are no operationId - based on the endpoint names and HTTP verbs).
index.html#/tagName
index.html#/tagName/operationId
You can use these permalinks in your Markdown markup:
description: >
This endpoint does things.
See [/my/otherEndpoint](#/tagName/myOtherEndpointId) for stuff
Notes:
Markdown links (such as above) currently open in a new browser tab (as with target="_blank") - see issue #3473.
HTML-formatted links foobar currently don't work.
Swagger Editor does not support such permalinks.
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)
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.