I'm getting 406 Not Acceptable responses when I'm trying to use the externalValue property in an example object on the swaggerhub mocked server.
Am I doing something wrong or this feature is not implemented on the swaggerhub mocking server?
API snippet
paths:
/test:
get:
responses:
"200":
description: OK!
content:
application/json:
schema:
type: string
format: binary
examples:
example:
externalValue: "https://jsonplaceholder.typicode.com/todos/1"
application/pdf:
schema:
type: string
format: binary
examples:
sampleFile:
externalValue: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
Postman API call
open api documentation
examples externalValue property
SwaggerHub mock server only supports JSON, XML, and YAML responses. If you request any other media types (e.g. Accept: application/pdf or Accept: image/png), a 406 response is returned.
SwaggerHub mock server does NOT support externalValue for sample responses. The mock ignores those examples and generates sample responses by other means, e.g. based on the response schema.
From the documentation (emphasis mine):
Generates JSON, XML and YAML responses based on response schemas and examples.
Supports enum, default, example, and examples (the first example is returned), except for externalValue examples.
Related
I have an OpenAPI document where an endpoint uses oneOf for the request body (this endpoint has 2 possible different schemas). In Swagger UI, I can only see one of the schemas where the endpoint is displayed, which I understand is normal. How could I display the other schema or link it, so I can access it easily?
The Schema tab in Swagger UI displays all subschemas of oneOf and anyOf schemas:
To reflect the alternatives on the Example Value tab, you'll need to manually define multiple request body examples, one for each schema. This will add a dropdown to Swagger UI so that the users can switch between the examples.
paths:
/something:
post:
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Foo'
- $ref: '#/components/schemas/Bar'
examples:
fooExample:
summary: An example of Foo data
value:
foo: hello
barExample:
summary: An example of Bar data
value:
bar: 123
I think there was an existing feature request to generate multiple examples for oneOf/anyOf subschemas automatically, but I can't find it. Feel free to submit a feature request yourself.
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)
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.