I'm getting [ERROR] Error resolving ./paths/daas/res_prod_acptd_art_cnts.yaml
java.net.URISyntaxException: Illegal character in opaque part at index 2, org.openapitools.codegen.SpecValidationException -Illegal character in opaque part at index 2 for the following yaml
openapi: 3.1.0
info:
title: test
description: test
# TODO: termsOfService field should be added later
contact:
name: test Support
email: test
version: 0.0.1
license:
name: Copyright
identifier: EPL-2.0
servers:
- url: http://localhost:8080/api
description: Localhost for development purposes
# TODO: Add the security requirments object later
security: []
tags:
- name: DaaS RES Production Service
description: Research workflow Production stage related DaaS Production Service APIs
paths:
# Production Service
/{tenantId}/counts:
$ref: 'paths/daas/res_prod_acptd_art_cnts.yaml'
$ref: 'paths/daas/res_prod_acptd_art_cnts.yaml'
post:
summary: Production Accepted Article Counts
description: API to request counts of production accepted articles by article classification type and other specified global filtering criteria.
tags:
- DaaS RES Production Service
operationId: postProductionAcceptedArticleCounts
requestBody:
description: Contains the parameter combination that must be applied to generate the response
content:
'application/json':
schema:
$ref: '../../components/daas/requestBodies/ReqPayloadProdAcptdArtCnts.yaml'
examples:
example-1:
value:
$ref: '../../components/daas/examples/ReqExProdAcptdArtCnts.yaml'
example-2:
value:
$ref: '../../components/daas/examples/ReqEx2ProdAcptdArtCnts.yaml'
example-3:
value:
$ref: '../../components/daas/examples/ReqEx3ProdAcptdArtCnts.yaml'
example-4:
value:
$ref: '../../components/daas/examples/ReqEx4ProdAcptdArtCnts.yaml'
required: true
responses:
'200':
$ref: '../../components/daas/responses/ResPayloadProdAcptdArtCnts.yaml'
'400':
$ref: '../../components/daas/responses/400BadRequest.yaml'
'401':
$ref: '../../components/daas/responses/401Unauthorized.yaml'
'415':
$ref: '../../components/daas/responses/415UnsupportedMediaType.yaml'
'500':
$ref: '../../components/daas/responses/500InternalServerError.yaml'
parameters:
- name: tenantId
in: path
description: Tenant ID of the tenant of which the caller is invoking the API of.
required: true
schema:
type: string
example: '1001'
Related
I have redoc-cli installed via npm
$ redoc-cli --version
0.13.20
Now I use it to build docs with the following
openapi: 3.1.0
info:
title: Sample API
version: '1.0'
contact:
email: some#email.com
description: Api description.
tags:
- name: sample tag
description: tag description
servers:
- url: http://localhost:3000
paths:
/int/methods/list:
post:
summary: Sample op
operationId: sample-op
description: Op description.
requestBody:
content:
application/json:
schema:
type: object
properties:
test:
$ref: '#/components/schemas/test'
tags:
- sample tag
components:
schemas:
test1:
title: Test
type: object
properties:
testType:
type: string
testOne:
type: string
test2:
title: Test 2
type: object
properties:
testType:
type: string
testTwo:
type: number
test:
title: Test Polymorph
oneOf:
- $ref: '#/components/schemas/test1'
- $ref: '#/components/schemas/test2'
discriminator:
propertyName: testType
mapping:
ONE: '#/components/schemas/test1'
TWO: '#/components/schemas/test2'
Still attempting to
$ redoc-cli build 04_interface/test.yaml
Prerendering docs
🎉 bundled successfully in: redoc-static.html (1061 KiB) [⏱ 0.179s]
Gives me a result as-if the whole discriminator was missing, i.e.
...instaed of the expected select box, as documented in redocly
I know redocly and redoc-cli are not the same, but redoc-cli used to support discriminators in the past, just at some point it seems to me that it stopped working - or there is some syntax niche I am missing.
So i found what the turning point is. Look at this example.
openapi: 3.1.0
info:
title: Sample API
version: '1.0'
contact:
email: some#email.com
description: Api description.
tags:
- name: sample tag
description: tag description
servers:
- url: http://localhost:3000
paths:
/sample-path:
post:
summary: Sample op
operationId: sample-op
description: Op description.
requestBody:
content:
application/json:
schema:
title: Test
type: object
properties:
prop1:
title: Test Polymorph
oneOf:
- $ref: '#/components/schemas/test1'
- $ref: '#/components/schemas/test2'
discriminator:
propertyName: testType
mapping:
ONE: '#/components/schemas/test1'
TWO: '#/components/schemas/test2'
prop2:
$ref: '#/components/schemas/testPolymorph'
tags:
- sample tag
/another-path:
post:
summary: Another op
operationId: another-op
description: Another op description.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/testPolymorph'
tags:
- sample tag
components:
schemas:
test1:
title: Test - Variant 1
type: object
properties:
testType:
type: string
testOne:
type: string
test2:
title: Test Variant 2
type: object
properties:
testType:
type: string
testTwo:
type: number
testPolymorph:
title: Test Polymorph
discriminator:
propertyName: testType
mapping:
ONE: '#/components/schemas/test1'
TWO: '#/components/schemas/test2'
oneOf:
- $ref: '#/components/schemas/test1'
- $ref: '#/components/schemas/test2'
This specs yields the following visualization
It seems the discriminator doesnt work for $refs, only if the $ref is on the top schema level.
I started an issue here https://github.com/Redocly/redoc/issues/2252
I've got an OpenAPI schema (edited it to be a minimal working example):
---
openapi: 3.0.0
info:
title: Players API
version: 0.0.1-alpha1
paths:
/players/{id}:
get:
responses:
'200':
description: OK
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Player'
- type: object
required:
- id
properties:
spec:
type: object
required:
- display_name
components:
schemas:
Player:
type: object
properties:
spec:
$ref: '#/components/schemas/PlayerSpec'
additionalProperties: false
PlayerSpec:
type: object
properties:
display_name:
type: string
description: The name of the player.
example: LeBron
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
additionalProperties: false
PlayerReference:
type: object
required:
- id
properties:
id:
type: string
example: 'lebron-23'
and after I run: redoc-cli bundle example.yaml to generate the docs I can see:
(basically id: lebron-23 is there -- i.e., the docs look as expected).
The problem is in order to make it work I had to add example: 'lebron-23' to the definition of a generic PlayerReference component but I'd rather move this example: 'lebron-23' line to this section instead:
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
<-------- add id.example here or something
Since environment is an object, an object-level example would look like this:
environment:
allOf:
- $ref: '#/components/schemas/PlayerReference'
- required:
- related
description: The environment to which the player belongs.
example:
id: lebron-23
This example will probably override any examples from allOf subschemas (rather than merge with them), so make sure to include all property values you want to see in this example.
I am new to Swagger, and I have being fixing some errors I got after importing the .json file into https://editor.swagger.io/ but I am getting this error.
Declared path parameter "PARAMETER" needs to be defined within every
operation in the path (missing in "get"), or moved to the path-level
parameters object
Here is the part that is giving me the error:
'/api/v1/images/{PARAMETER}/{type}':
get:
tags:
- Images
summary: 'summar'
operationId: DownloadFIle
consumes: []
produces:
- application/json
parameters:
- name: PARAMETER
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
responses:
'200':
description: Success
schema:
uniqueItems: false
type: array
items:
$ref: '#/definitions/CloudImageInfo'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'404':
description: Not Found
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
post:
tags:
- Images
summary: summary
description: " description"
operationId: UploadFile
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: imageFiles
in: formData
required: false
type: array
items: {}
collectionFormat: multi
uniqueItems: false
- name: PARAMETER
in: path
required: true
type: string
- name: type
in: path
required: true
type: string
responses:
'201':
description: Success
schema:
uniqueItems: false
type: array
items:
$ref: '#/definitions/CloudImageInfo'
'400':
description: Bad Request
schema:
$ref: '#/definitions/ErrorResponse'
'401':
description: Unauthorized
schema:
type: string
'500':
description: Server Error
schema:
$ref: '#/definitions/ErrorResponse'
can anyone point me where to look or what can I fix?
I've take the allOf examples in https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#models-with-composition, and applied them to parameters schema and responses schema. My allOf parameters and responses, however, show as undefined. When just using Pet instead of Cat, it works fine. Please let me know how to use Swagger's allOf
swagger: '2.0'
# This is your document metadata
info:
version: "0.0.0"
title: <enter your title>
# Describe your paths here
paths:
/test1:
# This is a HTTP operation
post:
description: bla bla
parameters:
- name: Pet
required: true
in: body
description: The Pet.
schema:
$ref: '#/definitions/Pet'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/Pet'
/test2:
# This is a HTTP operation
post:
description: bla bla
parameters:
- name: Cat
required: true
in: body
description: The cat.
schema:
$ref: '#/definitions/Cat'
# Expected responses for this operation:
responses:
# Response code
200:
description: Successful response
schema:
$ref: '#/definitions/Cat'
definitions:
Pet:
type: object
discriminator: petType
properties:
name:
type: string
petType:
type: string
required:
- name
- petType
Cat:
description: A representation of a cat
allOf:
- $ref: '#/definitions/Pet'
- type: object
properties:
huntingSkill:
type: string
description: The measured skill for hunting
default: lazy
enum:
- clueless
- lazy
- adventurous
- aggressive
required:
- huntingSkill
A type field is missing in Cat Definitions Object and therefore swagger-editor shows undefined.
Add type: object as follow can fix it:
Cat:
type: object
description: A representation of a cat
allOf:
I'm using the swagger editor to document an existing API that allows a path to support two different requests that differ only in their query parameter names. For example:
swagger: '2.0'
info:
title: example
version: 1.0.0
host: example.com
schemes:
- http
basePath: /WS
paths:
/Login:
post:
summary: Login
description: |
Log in
parameters:
- name: UserID
in: query
description: User ID
required: true
type: string
- name: Password
in: query
description: User password
required: true
type: string
responses:
'200':
description: Success
/Login:
post:
summary: Login
description: |
Log in
parameters:
- name: UserID
in: query
description: User ID
required: true
type: string
- name: Token
in: query
description: Authentication token
required: true
type: string
responses:
'200':
description: Success
Here I support requests to http://example.com/WS/Login?UserID=foo&Passoword=bar and http://example.com/WS/Login?UserID=foo&Token=dubdu22r8dwjgd767dg.
The swagger editor doesn't show any errors for the above yaml, but it only generates documentation for the second path (the one with UserId and Token queryparams), not both. Can someone point out where I'm going wrong? Thanks.
Edit:
If I change the second /Login: path to (for example) /Login1: then I see both paths in the documentation. Not a solution though.
It also occurs to me that I could specify one /Login: path with a required UserID parameter and optional Password and Token parameters. But how do I specify that exactly one of UserID and Password must be supplied?
You can use path parameters instead, try with:
swagger: '2.0'
info:
title: example
version: 1.0.0
host: example.com
schemes:
- http
basePath: /WS
paths:
/Login?UserID={id}&Password={password}:
post:
summary: Login
description: Log in
parameters:
- name: id
in: path
description: User ID
required: true
type: string
- name: password
in: path
description: User password
required: true
type: string
responses:
'200':
description: Success
/Login?UserID={id}&Token={token}:
post:
summary: Login
description: Log in
parameters:
- name: id
in: path
description: User ID
required: true
type: string
- name: token
in: path
description: Authentication token
required: true
type: string
responses:
'200':
description: Success