Comments (6)
I do not believe this is the right thing to do, for the following reason.
When (in your gist) you $ref
defs.yml#/Transaction
the only things which are in scope are:
type: object
properties:
id:
type: string
example: A11234
pattern: '[A-Z][0-9]{1,32}'
readOnly: true
account_id:
type: string
example: 05a2106b-92a4-4ee3-a6a3-c32f8b609de1
format: uuid
readOnly: true
operation_type:
type: string
enum:
- payment
- refund
example: payment
payment_method:
$ref: '#/PaymentMethod'
directly, and the value of #/PaymentMethod
(indirectly).
PaymentMethod
is defined as
type: object
x-discriminator:
propertyName: type
mapping:
visa: "#/paymentMethodVisa"
mastercard: "#/paymentMethodMastercard"
amex: "#/paymentMethodAmex"
properties:
type:
description: The type of Payment Method used for Transaction
type: string
In OAS 3.0, it is not defined if the discriminator
object mapping
values, when they contain a $ref
-like value resolve against the current document or the root document.
Because they are not a JSON Schema $ref
object, our resolver effectively can't see them, and I'm reluctant to add a special case for discriminator.mapping
, especially here, where we're actually looking at x-discriminator
.
Personally, I would change the x-discriminator.mapping
values to be plain schema names (which are presumably resolved against #/components/schemas/
in the root/resolved document, and $ref
the schema definitions from your root document.
It might also be worth raising this issue on the OAS repository (in OAS v3 terms and referencing discriminator
and not x-discriminator
), because it is confusing, and I say that as an OAI TSC member 😄
from oas-kit.
Thanks for mulling it over and giving a detailed response. I agree that it's very confusing.
Personally, I would change the x-discriminator.mapping values to be plain schema names (which are presumably resolved against #/components/schemas/ in the root/resolved document, and $ref the schema definitions from your root document.
Are you suggesting that references should be expressed the following way?
PaymentMethod:
type: object
x-discriminator:
propertyName: type
mapping:
visa:
$ref: "foo.yml#/paymentMethodVisa"
mastercard:
$ref: "foo.yml#/paymentMethodMastercard"
amex:
$ref: "foo.yml#/paymentMethodAmex"
properties:
type:
description: The type of Payment Method used for Transaction
type: string
from oas-kit.
Not quite - though that might be my preferred structure of discriminator
in OAS v4!
I would (for now) do something like this:
swagger.yml:
swagger: "2.0"
info:
title: API
version: 1.0.0
paths:
/:
get:
responses:
default:
description: OK
schema:
$ref: 'defs.yml#/Transaction'
definitions:
paymentMethodVisa:
$ref: 'defs.yml#/paymentMethodVisa'
defs.yml:
Transaction:
...
x-discriminator:
propertyName: type
mapping:
visa: "paymentMethodVisa"
...
paymentMethodVisa:
...
...
I hope I've explained the approach ok?
from oas-kit.
Ah ok, I think I get it. Your suggestion is worth a try.
Do you think it's worth me suggesting the ref syntax this as an improvement for the next version of OAS? I love returning polymorphic types but so far Swagger/OAS has made it quite hard to do so.
from oas-kit.
Do you think it's worth me suggesting the ref syntax this as an improvement for the next version of OAS?
I think it would be worth getting some clarity on why it wasn't done this way, and around the expected resolution rules when discriminator
occurs inside a sub-document.
from oas-kit.
Closing due to inactivity. Will reopen if workable changes come out of discussions on OAI/OpenAPI-Specification#1661 or any new issue you chose to open over at https://github.com/OAI/OpenAPI-Specification
from oas-kit.
Related Issues (20)
- Is it possible to remove the vulnerability introduced by ajv? HOT 2
- Dependency on should(js) causes typescript compilation problems when other dependencies use chai HOT 1
- swagger2openapi: timestamp events get converted to YAML timestamps
- swagger2openapi: missed request body contenttype after conversion from swagger v2 to openAPI v3.0.x
- Planned support for OpenAPI 3.1? HOT 6
- @ts-check command in index file make typescript project fail to build
- While upgrading swagger2openapi module with latest version @7.0.8, dependency module node-fetch is not updated to latest version HOT 3
- What does this error mean? > #/paths/~1v1~1action~1amend/post/parameters/3/schema, expected 'string' to be 'number' HOT 1
- Dockerfile vulnerability - `Specify at least 1 USER command in Dockerfile with non-root user as argument` HOT 1
- swagger2openapi报错,Swagger schema parse error! HOT 1
- Field "description" values are usurped by the schema's definition description (used via Redoc) HOT 4
- openAPI validator says header in components is invalid and should contain name when specs say differently. HOT 1
- Swagger 2.0 to 3.0 convertor for SwashBuckle.core (.Net) HOT 1
- TS types for oas-validator HOT 1
- Understanding the opinionated nature of this library HOT 7
- Give an option to mark not required fields as nullable HOT 1
- Allow the same operationId under different tags HOT 5
- Update yaml to v2 HOT 4
- [swagger2openapi][components] Add a prefix to generated components HOT 2
- Error reported when swagger. schemas is empty
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from oas-kit.