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.
Related
I'm trying to build a simple Swagger model:
PlayerConfig:
type: object
required:
- kind
- player_id
properties:
kind:
type: string
example: PlayerConfig
player_id:
type: string
example: "foo"
description: "bar"
sports_config:
oneOf:
- $ref: '#/components/schemas/PlayerConfig'
discriminator:
propertyName: kind
For some reason the generated HTML does not show the player_id's example field. This makes me think I'm not doing this correctly.s
So the question is if using a model as a type can in fact be done as I'm trying to do. example field does get rendered if its parent is parameters: instead of properties:.
Update: I read Object and Property Examples section on https://swagger.io/docs/specification/adding-examples/ and it seems like my code snippet should have worked.
Update #2: I actually downloaded redoc-cli (which is a CLI tool for OpenAPI -> html bundle) and took a sample spec from Swagger Editor that has example field under properties that mimics my problem and it looks like it's expected (see the screenshot I attached):
If the string value contains spaces (or some other special characters), you should enclose it in quotes. So the line should read
example: "LeBron James"
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.
I am trying to add extra information to model items in Swagger. The documentation says that GFM syntax can be used in description fields but this is not working in all places.
Here is a minimal dummy example of the problem:
swagger: '2.0'
info:
title: Example API
description: (1) This is the API description containing some *rich* **text**
version: "1.0.0"
paths:
/products:
get:
summary: Product Types
description: (2) This is the path description also containing some *rich* **text**
responses:
200:
description: (3) This is a response description also containing some *rich* **text**
schema:
type: array
items:
$ref: '#/definitions/Product'
definitions:
Product:
description: (4) This is a model description where *rich* **text** does not work
type: object
properties:
product_id:
type: string
description: (5) This is a field description where *rich* **text** does not work
The schema object documentation says that I should be able to use Markdown in the place marked as (4) above but doesn't say anything about place (5).
I want to add Markdown to either of the two places in the Model section. How can I get this to work?
Swagger Editor does not support Markdown in model descriptions. From https://github.com/swagger-api/swagger-editor/issues/682:
For rendering JSON Schema object we are using json-schema-view-js lib which does not support Markdown. Swagger Editor can not change behavior of this lib and this behavior is not something common to add to the lib.
If you need this feature you could fork swagger-editor and/or json-schema-view-js and implement the feature/fix yourself, then submit a pull request.
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.