Comments (12)
Holy Moly, they really changed it without any backward compatibility:
from openapi3-ts.
Also, which tool would you recommend to validate 3.1 specification?
A good list of validators and compatibility is maintained here: https://openapi.tools/#data-validators
Support for 3.1 has a "slow adoption" so I am more inclined to still support 3.0 and 3.1 in this lib if we can handle the complexity.
Take a look also to this one: https://github.com/seriousme/openapi-schema-validator
from openapi3-ts.
What do you need in your use cases @RobinTail 3.0.0 or 3.1.0?
For my case, I need to provide users of my library with a tool that generates the specification of their API, that could be used for the following cases:
- general documentation to share between BE and FE developers
- development support on the tool level, to visualize the schema and perform sample API requests:
- testing and mocking
I'm not sure at the moment which OpenAPI versions are currently supported by Webstorm and Postman, but Swagger still only supports 3.0.
I'm going to find out and let you know soon.
Thank you @pjmolina
from openapi3-ts.
It's ok, @OrIOg . I prepared another one: #85 , according to @pjmolina vision. It's much simpler and might fulfill all needs.
from openapi3-ts.
CC @OrIOg
from openapi3-ts.
Ok, I found the PR that describes the reason:
#78
And this looks a bit strange to me, since my link to the spec is taken from the swagger.io website:
https://swagger.io/specification/
Schema Object
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00 1.
For more information about the properties, see JSON Schema Core 2 and JSON Schema Validation 3. Unless stated otherwise, the property definitions follow the JSON Schema.
The document (3) clearly says that the property MUST be boolean:
https://datatracker.ietf.org/doc/html/draft-wright-json-schema-validation-00
However the one referred in the PR says it must be a number:
https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.3
Presuming that the one in the PR is newer, it's still questionable how to deal with the complains in Swagger validator (see the screenshot)
from openapi3-ts.
Here is another link to the documentation that describes exclusiveMaximum
as boolean:
https://swagger.io/docs/specification/data-models/data-types/?sbsearch=exclusiveMaximum
It's based on OpenAPI 3.0 and as per my understanding it should not be breaking changes in 3.1 as well.
So, it's still confusing.
from openapi3-ts.
Looks like the change is coming from different versions of JSON Schema. OpenAPI is not redefining them, but using them directly from JSON Schema.
See: https://json-schema.org/understanding-json-schema/reference/numeric.html
- Previous versions used
exclusiveMaximum
andexclusiveMinimum
as booleans in combination withmaximum
andminimum
. Probably used at Swagger. 2.x. - Draft 4 in JSON Schema changed and broke the compatibility to be:
exclusiveMaximum
andexclusiveMinimum
numbers.
Latest spec OpenAPI 3.1.0 uses JSON Schema Specification Draft 2020-12 (the number version)
So, my best guess is we should stick to numbers
.
Take in mind (last time I checked) Swagger Editor (from swagger.io) was still supporting spec. v2. and not yet 3.x
from openapi3-ts.
Yeah, I see.
So, if the library is currently only 3.1
compatible, should we reflect it on openapi
version here, for example:
https://github.com/metadevpro/openapi3-ts/blob/master/src/dsl/OpenApiBuilder.ts#L16 ?
And there also a lot of comments/jsdoc in the code that refer to 3.0
, while the versions are so different and backward incompatible.
What do you think?
Also, which tool would you recommend to validate 3.1
specification?
Swagger.io validates 3.0.x
only.
from openapi3-ts.
Indeed, we can enforce 3.1.0 but also thinking about relaxing the type for exclusiveMaximum
and exclusiveMinimum
to be number | boolean
to help people to transition from OpenAPI 3.0 (boolean) to 3.1. (number)
What do you think it would be more useful?
What do you need in your use cases @RobinTail 3.0.0 or 3.1.0?
from openapi3-ts.
Indeed, we can enforce 3.1.0 but also thinking about relaxing the type for exclusiveMaximum and exclusiveMinimum to be number | boolean to help people to transition from OpenAPI 3.0 (boolean) to 3.1. (number)
What do you think it would be more useful?
Well, I believe that ideally, in a case like this, the type should depend on the version literal and be generic.
For example, consider this:
type OpenApiVersion = `3.${number}.${number}`;
export interface OpenAPIObject<V extends OpenApiVersion> {
openapi: V;
// ...
}
export interface SchemaObject<V extends OpenApiVersion> {
// ...
exclusiveMaximum?: V extends `3.1.${number}` ? number : boolean;
}
It requires at least Typescript 4.1 to support type literals.
And perhaps more entities, and most likely the OpenApiBuilder
class, would have to become generic too.
I'm not sure about this yet, since it increases the code complexity.
But the benefit of it — keeping the single but generic type declaration.
I will think more on other ways too.
@pjmolina
from openapi3-ts.
Holy Moly, they really changed it without any backward compatibility:
I should have checked it in depth before reporting the issue & the PR. It is my bad, sorry.
It does seems that Swagger revisions isn't really support 3.1 even though they talk about the openapi 3.1 in the version
But it would be great to be able to support both versions.
I'll try testing @RobinTail 's PR on my side, even with the breaking changes it might be the way to do it correctly. There might be a way by extending said schema and changing definition, but pros & cons are to be established
from openapi3-ts.
Related Issues (20)
- No index signature with a parameter of type 'string' was found on type 'ISpecificationExtension'. HOT 18
- import { OpenAPIObject } from "openapi3-ts/src/model/openapi31" doesn't work with mocha and ESM HOT 2
- Cannot import `oas31` using ESM in `[email protected]` HOT 5
- importing mjs fails in node HOT 3
- API Parameter description output to wrong place HOT 3
- Validation error: `examples` must be an array HOT 5
- OAS 3.1: Support for const keyword HOT 1
- Source files are published in the package HOT 2
- An in-range update of @types/chai is breaking the build 🚨 HOT 7
- Add "isDereferencedObject" helper method HOT 1
- When using oneOf with objects that have different properties, typescript assumes the list type and breaks HOT 4
- Uniftying with `@types/json-schema`? HOT 1
- Usage question HOT 1
- how to remove/update a path? HOT 1
- Documentation HOT 5
- exclusiveMinimum/Maximum should not be booleans
- v3.0: __exportStar is not defined HOT 10
- Targeting certain OpenAPI versions HOT 5
- 4.0: the module exports OAS 3.1 only HOT 6
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 openapi3-ts.