mermade / oas-kit Goto Github PK
View Code? Open in Web Editor NEWConvert Swagger 2.0 definitions to OpenAPI 3.0 and resolve/validate/lint
Home Page: https://mermade.org.uk/openapi-converter
License: BSD 3-Clause "New" or "Revised" License
Convert Swagger 2.0 definitions to OpenAPI 3.0 and resolve/validate/lint
Home Page: https://mermade.org.uk/openapi-converter
License: BSD 3-Clause "New" or "Revised" License
Sorry if this is off-topic. I would like to use swagger-codegen to create a simple SDK for an API that's documented with openapi3. But since swagger-codegen isn't quite there yet for openapi3, I'm looking for a way to convert our openapi3 spec to openapi2. Is that possible to do with swagger2openapi?
A file which oas-validator passes as valid, is giving an odd error on resolution:
Resolution error: Expected object or boolean as schema, got string
I'm getting this in speccy@beta
(the release/0.8.0 branch) from the following code:
return resolver.resolve(openapi, options.source, options)
.catch(err => {
console.error('Resolution error:', err);
process.exit(1);
});
Adding some debug to resolveContent
to see what options are being sent in, it looked like this:
{ resolve: true,
cache: [],
externals: [],
externalRefs: {},
rewriteRefs: true,
status: 'undefined',
filters: [ [Function: convert] ],
verbose: 0,
source: '../apis/tmp/charging-service/docs/openapi.json',
origin: '../apis/tmp/charging-service/docs/openapi.json',
openapi:
{ openapi: '3.0.0',
tags: [Array],
info: [Object],
servers: [Array],
paths: [Object],
components: [Object] } }
I noticed that i was specifying defaults for a few things that are being defaulted in oas-resolver now, especially cache
which was []
and is now {}
in oas-resolver, and externalRefs
which is the other way around.
Trimming these uneccessary defaults down to the minimum did not help:
{ resolve: true,
filters: [ [Function: convert] ],
verbose: 0,
source: '../apis/tmp/charging-service/docs/openapi.json',
origin: '../apis/tmp/charging-service/docs/openapi.json' }
Still getting that error, and verbose doesn't show anything more either.
Internal resolution #/response_status/bad_request
Finished internal resolution
Creating initial clone of data at #/paths/~1api~1v1~1charging_profiles~1%7Bcharging_profile_uuid%7D/get/responses/400/content/application~1json/example
CACHED /Users/phil.sturgeon/src/apis/tmp/charging-service/docs/components/examples/examples.json #/response_status/resource_not_found_status
Finished internal resolution
Expected object or boolean as schema, got string
Resolution error: Expected object or boolean as schema, got string
I have split a Swagger specification into multiple files. swagger2openapi
cannot resolve the file "ok.yaml" because it tries to read "subdir2/ok.yaml" instead of "subdir1/subdir2/ok.yaml".
$ swagger2openapi -r index.yaml
{ Error: ENOENT: no such file or directory, open '/./subdir2/ok.yaml'
at Error (native)
errno: -2,
code: 'ENOENT',
syscall: 'open',
path: '/./subdir2/ok.yaml' }
index.yaml:
swagger: '2.0'
info:
version: 0.0.0
title: Simple API
paths:
/test:
$ref: ./subdir1/test.yaml
subdir1/test.yaml:
get:
responses:
200:
description: OK
schema:
$ref: ./subdir2/ok.yaml
subdir1/subdir2/ok.yaml:
type: object
properties:
name:
type: string
When validating an openapi 3.0 specification, the validation does not check for a valid $ref
as part of a PathItem Object. As a result PathItem objects that use $ref's (but that cannot be resolved e.g. to missing files) are incorrectly passing validation.
There is an explicit check for each child field name
A valid PathItem Object according to the spec may include a $ref.
Example snippet:
paths:
/SomePath:
$ref: "paths/something.yml#/paths/SomePath"
I would expect behaviour for valid spec to be one of:
Or something else equally helpful
3.4.0
to 3.4.1
.This version is covered by your current version range and after updating it in your project the build failed.
lerna is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 10 commits.
05a27a6
chore(release): publish v3.4.1
f7fdc77
fix(publish): Overwrite Yarn registry proxy when encountered
06a9479
fix(publish): Set token on npm config, allow third-party registries to remain non-compliant
987fd26
fix(bootstrap): Constrain npm-conf argument object to options.registry only
597606c
fix(add): Allow --registry option
25af71d
fix(npm-conf): Do not overwrite defaults with undefined cli keys
159a0b0
fix(conventional-commits): Upgrade angular preset, ensure header is not duplicated
9752f3e
fix(conventional-commits): Upgrade dependencies
a60a0c3
docs: Add 'lerna create' command to README.md (#1680)
265ec0c
docs(readme): update independent mode instructions (#1701)
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
A swagger file without a schemes array results in an empty OAS 3 servers
array.
Consider the following minimal (valid) Swagger 2 file:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger 2.0 Without Scheme"
},
"host": "example.com",
"paths": {}
}
When converted, this results in the following output:
{
"openapi": "3.0.0",
"servers": [],
"info": {
"version": "1.0.0",
"title": "Swagger 2.0 Without Scheme"
},
"paths": {}
}
Losing any information to do with the host.
When there is a basePath
, like so:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger 2.0 Without Scheme"
},
"host": "example.com",
"basePath": "/api",
"paths": {}
}
It converts to the following:
{
"openapi": "3.0.0",
"servers": [
{
"url": "/api"
}
],
"info": {
"version": "1.0.0",
"title": "Swagger 2.0 Without Scheme"
},
"paths": {}
}
Adding a scheme makes it work for both of these cases. Maybe we could create a scheme
-less server url and output that?
I had a quick look at the code and couldnt figure out where to add test cases such as the above. Happy to send a PR to fix this if you tell me where in the code to look!
We're using it pretty extensively over at https://readme.io/ for some OAS 3 related stuff! We're happy to contribute back.
After cloning and doing npm i
I still get a failure on the require for node-fetch
. Here's the command-line and stack trace:
node ./oas-kit/packages/swagger2openapi/swagger2openapi.js -o spec.v3.json spec.json
module.js:538
throw err;
^
Error: Cannot find module 'node-fetch'
at Function.Module._resolveFilename (module.js:536:15)
at Function.Module._load (module.js:466:25)
at Module.require (module.js:579:17)
at require (internal/module.js:11:18)
at Object.<anonymous> (/Users/me/oas-kit/packages/swagger2openapi/index.js:9:15)
at Module._compile (module.js:635:30)
at Object.Module._extensions..js (module.js:646:10)
at Module.load (module.js:554:32)
at tryModuleLoad (module.js:497:12)
at Function.Module._load (module.js:489:3)
I'm using the current build, found it from https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md
Hello! We are trying to build an application that uses your library. Unfortunately, there seems to be something wrong... We encounter a problem when we try to validate our test OAS which utilizes numbers, specifically in the server object definition. It seems that your validator does not like numbers in the OAS.
Here is our error:
AssertionError: expected 3000 to have type string
expected 'number' to be 'string'
at Assertion.fail (node_modules/should/cjs/should.js:258:17)
at Assertion.value [as type] (node_modules/should/cjs/should.js:335:19)
at checkServers (node_modules/swagger2openapi/validate.js:119:43)
at Object.validateSync (node_modules/swagger2openapi/validate.js:349:3)
And here is our server object definition, note the default port number:
{
"servers": [
{
"url": "http://localhost:{port}/{basePath}",
"description": "The location of the local test server.",
"variables": {
"port": {
"default": 3000
},
"basePath": {
"default": "api"
}
}
}
]
}
We thought that we were following proper OAS specification as the official specification page has a very similar example which can be seen here:
{
"servers": [
{
"url": "https://{username}.gigantic-server.com:{port}/{basePath}",
"description": "The production API server",
"variables": {
"username": {
"default": "demo",
"description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
},
"port": {
"enum": [
8443,
443
],
"default": 8443
},
"basePath": {
"default": "v2"
}
}
}
]
}
swagger2openapi
converts x-required
, x-nullable
and a few others vendor extensions to corresponding OpenAPI 3 features.
Would be great to also support x-discriminator
:
x-discriminator:
propertyName: type
mapping:
visa: "#/definitions/paymentMethodVisa"
mastercard: "#/definitions/paymentMethodMastercard"
amex: "#/definitions/paymentMethodAmex"
One of the things to not forget is to map JSON pointers from mapping
field to new locations.
As discussed with @philsturgeon - this would allow pulling JSON schema documents and having them magically transformed into OpenAPI schema objects.
Branch | Build failing 🚨 |
---|---|
Dependency | webpack |
Current Version | 4.17.3 |
Type | devDependency |
This version is covered by your current version range and after updating it in your project the build failed.
webpack is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 12 commits.
ee7d948
4.18.0
de85978
Merge pull request #7732 from xtuc/chore-bump-webassemblyjs11
4e02cac
chore: bump webassemblyjs
52e1630
bump webassemblyjs
e0e0061
Merge branch 'master' into chore-bump-webassemblyjs11
c9d6ec1
feat: remove wasm-opt
075208d
fix: merging
38c3403
Merge remote-tracking branch 'upstream/master' into chore-bump-webassemblyjs11
8214d56
chore: bump webassemblyjs
59114c1
chore: bump webassemblyjs
b310b9b
feat: remove LEB128 opt
f744c4a
chore: bump webassemblyjs 1.6.0
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
Branch | Build failing 🚨 |
---|---|
Dependency | lerna |
Current Version | 3.3.0 |
Type | devDependency |
This version is covered by your current version range and after updating it in your project the build failed.
lerna is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 13 commits.
5da1319
chore(release): publish v3.3.1
367bf4e
test(integration): Avoid inexplicable snapshot comparison errors on Windows
5880788
test(helpers): Replace normalize-test-root with augmented placeholder serialization
ed16536
test(helpers): Make serialize-tempdir placeholder consistent with normalize-test-root
00842d6
fix(create): Upgrade whatwg-url to ^7.0.0
ebb7ee4
fix(prompt): Upgrade inquirer to ^6.2.0
b8d11b8
chore(deps): Update eslint + jest
7bd3179
chore: flailing around trying avoid 'no visual difference' snapshot garbage on Windows
b8915e7
fix(run-lifecycle): Remove repetitive error logging
a379266
chore(helpers): Normalize newlines to coddle windows
2a6f0a4
fix(publish): Tell yarn to stop creating git tags
ac0baa7
test(integration): avoid quoting arguments to coddle windows
b084293
fix(import): Handle filepaths with spaces more robustly (#1655)
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
When using a relative URL in the openIdConnectUrl
field, validation fails. When using an absolute URL, validation passes.
According to the spec, relative URLs are allowed. I did not try other URLs, but it's possible this issue exists for other properties.
I opened this similar issue in swagger-editor, but it seems like they are using this engine for validation, so I think the underlying issue may be with the validator in this project.
swagger-api/swagger-editor#1709
I can close this related issue if that project does depend on this one.
I found out about this project through the openapi.tools website. Using Validation engine v2.11.5 (hosted)
api-spec-converter currently uses swagger2openapi 2.x, but we have a request to upgrade to latest. Apparently swagger2openapi 2.x can cause problems problems due to mutation of the Object prototype, which was fixed here
When I upgrade to 3.x, however, our tests stop working. Running mocha
outputs:
_mocha [options] {path-to-specs}...
Options:
# ... a bunch of usage ...
Not enough non-option arguments: got 0, need at least 1
Any idea what could be going wrong here?
Link objects with operationRef properties do not have $ref properties, yet oas-validator complains that they do.
Here is what my link object looks like:
"ReviewsWithOperationRef": {
"operationRef": "#/paths/~1products~1{id}~1reviews/get",
"parameters": {
"id": "$request.path.product-id",
"product-tag": "$request.query.product-tag"
}
}
And when I try to validate my OAS, I get the following message:
status: false
message: |-
Failed OpenAPI3 schema validation: [
{
"keyword": "required",
"dataPath": "/components/links/ReviewsWithOperationRef",
"schemaPath": "#/required",
"params": {
"missingProperty": "$ref"
},
"message": "should have required property '$ref'",
"schema": {
"$ref": {
"type": "string",
"format": "uriref"
}
},
"parentSchema": {
"type": "object",
"required": [
"$ref"
],
"properties": {
"$ref": {
"type": "string",
"format": "uriref"
}
},
"description": "A simple object to allow referencing other components in the specification, internally and externally. The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules. For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification."
},
"data": {
"operationRef": "#/paths/~1products~1{id}~1reviews/get",
"parameters": {
"id": "$request.path.product-id",
"product-tag": "$request.query.product-tag"
}
}
},
...
]
context: '#/'
When I try to add the $ref property as suggested like in the following:
"ReviewsWithOperationRef": {
"$ref" : "blah",
"operationRef": "#/paths/~1products~1{id}~1reviews/get",
"parameters": {
"id": "$request.path.product-id",
"product-tag": "$request.query.product-tag"
}
}
... oas-validator gives the thumbs up.
However, link objects with operationRef properties do not have $ref properties.
Here is the link object documentation link again for easy reference.
Thanks!
Just a note, I have the exact same link object but with an operationId property instead of an operationRef property and oas-validator does not complain that it is missing a $ref property.
I am working with the latest version of oas-validator, version 1.1.7.
When converting the following endpoint in petstore.yaml from OAS2 to OAS3 using the online converter:
/pet/findByStatus:
get:
tags:
- pet
summary: Finds Pets by status
description: Multiple status values can be provided with comma separated strings
operationId: findPetsByStatus
produces:
- application/xml
- application/json
parameters:
- name: status
in: query
description: Status values that need to be considered for filter
required: true
type: array
items:
type: string
enum:
- available
- pending
- sold
default: available
collectionFormat: csv
I got the following result in OAS3:
/pet/findByStatus:
get:
tags:
- pet
summary: Finds Pets by status
description: Multiple status values can be provided with comma separated strings
operationId: findPetsByStatus
parameters:
- name: status
in: query
description: Status values that need to be considered for filter
required: true
style: form
schema:
type: array
items:
type: string
enum:
- available
- pending
- sold
default: available
collectionFormat: csv
in OAS2 should be converted to the following in OAS3 instead:
in: query
description: Status values that need to be considered for filter
required: true
style: form
explode: false
but in the output generated by the online converter, explode: false
is missing.
Ref:
Am I understanding OAS3 correctly in terms of how "collectionFormat: csv" (OAS2) should be defined in OAS3?
Branch | Build failing 🚨 |
---|---|
Dependency | ajv |
Current Version | 5.1.5 |
Type | dependency |
This version is covered by your current version range and after updating it in your project the build failed.
ajv is a direct dependency of this project this is very likely breaking your project right now. If other packages depend on you it’s very likely also breaking them.
I recommend you give this issue a very high priority. I’m sure you can resolve this 💪
The new version differs by 8 commits.
ff9f93a
5.1.6
0d6ae42
fix: traverse only schema objects, fixes #521
daf7d6b
docs: using with draft-04
9f0b563
Merge pull request #508 from epoberezkin/greenkeeper/nyc-11.0.2
55727d9
test: remove node v0.12, v5, add v8 to travis test
eac5902
chore(package): update nyc to version 11.0.2
f1c9f15
Merge pull request #507 from epoberezkin/greenkeeper/chai-4.0.1
d74a381
chore(package): update chai to version 4.0.1
See the full diff
There is a collection of frequently asked questions and of course you may always ask my humans.
Your Greenkeeper Bot 🌴
Branch | Build failing 🚨 |
---|---|
Dependency | ajv |
Current Version | 5.1.1 |
Type | dependency |
This version is covered by your current version range and after updating it in your project the build failed.
ajv is a direct dependency of this project this is very likely breaking your project right now. If other packages depend on you it’s very likely also breaking them.
I recommend you give this issue a very high priority. I’m sure you can resolve this 💪
The new version differs by 13 commits.
29e6238
5.1.2
9e5eeb1
Merge branch 'blainesch-patch-1'
fc66d31
docs: it.util.equal
d01a0b8
Expose equal from util.
bd1af60
Merge branch 'boenrobot-uglify3'
a7804bd
Made bundle.js write the uncompressed bundle only when standalone is present. Previously, it would instead write it, and remove it later if applicable.
38808e1
Merge branch 'master' into uglify3
5d9c93b
Merge pull request #484 from epoberezkin/greenkeeper/initial
be552a6
Tweaked bundle.js to support UglifyJS3.
8ffd98c
use uglify-js 2.x
f3abd13
Merge branch 'master' into greenkeeper/initial
4b7e422
docs(readme): add Greenkeeper badge
0829178
chore(package): update dependencies
See the full diff
There is a collection of frequently asked questions and of course you may always ask my humans.
Your Greenkeeper Bot 🌴
3.4.1
to 3.4.2
.This version is covered by your current version range and after updating it in your project the build failed.
lerna is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 6 commits.
6afcde7
chore(release): publish v3.4.2
bef9a83
chore: bump transitive dependencies
3d68d87
chore: bump dev dependencies
a89ae62
fix(publish): Prevent retries during access validation so third-party registries are skipped faster
7ba41a6
fix(publish): Use modern auth resolution
ef47f2a
docs(version): document the —yes option (#1715)
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
3.1.0
to 3.1.1
.This version is covered by your current version range and after updating it in your project the build failed.
webpack-cli is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
Webpack CLI version 3.1.1 comes with minor fixes to infrastructure, fixing bugs, synchronization with webpack and updating the build system.
For a full overview of changes done, you can view it here
Monorepo packages has also been updated as patches and can be safely updated.
The new version differs by 36 commits.
e3119b6
v0.1.1
a0afc35
chore: v.3.1.1
0ffede1
fix(schema): resolve references in schema (#605)
6be0478
chore(fix): fix clean all script
91cc499
chore(tests): added first ts test for info package (#584)
1a8099c
Merge pull request #604 from sendilkumarn/fix-tslint-issues
e425642
chore(lint): remove or replace console.log with console.error
db5f570
chore(lint): turn off console log warning
cf0bf4a
chore(lint): fix tslint warnings
1e0fa65
chore(ci): fix commitlint (#592)
b8d544b
feat(types): types for packages (#578)
936e7c1
chore(ci): Add a status badge for the azure pipelines CI build (#601)
d892b4d
chore(deps): resync package-lock, upgrade major version
2910645
docs(contribution): fix the setup workflow #591 (#597)
2588394
chore(ci): add commitlint when trying to commit (#595)
There are 36 commits in total.
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
Hi there,
We are writing OpenAPI 3.0.0 definitions and recently added this package to our gulp tasks for validation. We're getting the following error when using deprecated: true
on a property definition.
[16:52:05] Starting 'validate'...
[16:52:05] #/components/schemas/channelObject/properties/alias
Schema object cannot have additionalProperty: deprecated
Early on, we had no issues using the Swagger Editor, indeed the HTML output was nicely grayed out so I'd assumed that it was a valid usage (see screen shot).
Thanks for having a look and making such a useful tool!
Not all the refs are fixed up after conversion. The internal ones (not to #/definitions
) are not.
I checked your code and I'm not sure whether we can fix it efficiently but maybe you know how to do it.
Input:
swagger: '2.0'
info:
version: '1.0'
title: Demo API
paths:
"/test":
get:
responses:
'200':
description: OK
schema:
type: object
properties:
default:
title: Check
type: object
properties:
message:
type: string
description: bla
database:
"$ref": "#/paths/~1test/get/responses/200/schema/properties/default"
Output with broken ref:
openapi: 3.0.0
servers: []
info:
version: '1.0'
title: Demo API
paths:
"/test":
get:
responses:
'200':
description: OK
content:
"*/*":
schema:
type: object
properties:
default:
title: Check
type: object
properties:
message:
type: string
description: bla
database:
# Broken ref below
"$ref": "#/paths/~1test/get/responses/200/schema/properties/default"
When I'm trying to validate (invalid) oAPI 3.0 schema, this exception gets thrown.
Log:
ReferenceError: contentType is not defined
at checkResponse (/home/markov/Projects/tapeer-definitions/node_modules/swagger2openapi/validate.js:502:21)
at checkPathItem (/home/markov/Projects/tapeer-definitions/node_modules/swagger2openapi/validate.js:720:21)
at validateSync (/home/markov/Projects/tapeer-definitions/node_modules/swagger2openapi/validate.js:1025:13)
at /home/markov/Projects/tapeer-definitions/node_modules/swagger2openapi/validate.js:1219:9
at Generator.next (<anonymous>)
at onFulfilled (/home/markov/Projects/tapeer-definitions/node_modules/co/index.js:65:19)
at /home/markov/Projects/tapeer-definitions/node_modules/co/index.js:54:5
at new Promise (<anonymous>)
at co (/home/markov/Projects/tapeer-definitions/node_modules/co/index.js:50:10)
at Object.validate (/home/markov/Projects/tapeer-definitions/node_modules/swagger2openapi/validate.js:1214:5)
And yea, if you take a look at the source, it really tries to do weird stuff:
checkSchema(contentType.schema,{},'schema',openapi,options);
Even my IDE complains. Have you thought about adding ESLint & Prettier to the project, to avoid such simple bugs?
I'm running version 2.11.16
from NPM. I've successfully fixed it and will submit PR in a minute.
Feature request: I would be very nice to provide context info to help locate the errors reported on validation.
Swagger Editor reports a semantic error for parameters which are marked as query but are defined in the URI template as part of the path.
Semantic error at paths./v3/companies/{company_id}/seats/{uuid}
Declared path parameter "uuid" needs to be defined as a path parameter at either the path or operation level
'/v3/companies/{company_id}/seats/{uuid}':
parameters:
- name: company_id
in: path
description: Company UUID
example: 6bc8bb80-1e32-0136-eb32-0242ac11530c
schema:
type: string
format: UUID
required: true
- name: uuid
in: query
description: User UUID
example: '123456'
schema:
type: string
format: uuid
required: true
Using speccy by @philsturgeon and running speccy lint openapi.yaml
where securitySchemes
is defined as:
securitySchemes:
'Header Token':
type: apiKey
in: header
name: x-auth-token
'URL Token':
type: apiKey
in: query
name: auth_token
This will result in
Specification schema is invalid.
#/components/securitySchemes/Header Token
component name invalid
For both "Header Token" and "URL Token". Using a key without a space does work.
I believe the doc is correct since it works in both ReDoc and Swagger editor.
Could be fixed by updating this regex to allow spaces.
/^[a-zA-Z0-9\.\-_ ]+$/
potentially?
version: 1.1.7
{
"name": "indexer",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/Indexer"
},
"description": "The definition of the indexer to create or update."
}
"requestBody": {
"content": {
"application/json": {
"description": "The definition of the indexer to create or update.",
"schema": {
"$ref": "#/components/schemas/Indexer"
}
}
}
}
"requestBody": {
"content": {
"application/json": {
"description": "The definition of the indexer to create or update.",
"schema": {
"$ref": "#/components/schemas/Indexer"
}
}
},
"required": true
}
According to https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#request-body-object, required
defaults to false
, so it needs to be set to true
explicitly 🙂
Hi @MikeRalphson! Are there any plans for bundling a JS library for converting specs directly within the browser environment?
Was running this package transiently in production and ran into an issue. It looks like this project uses should
to validate schemas, which isn't great, since should
ends up creating a should
property on the Object prototype, potentially causing issues with other properties named should
anywhere.
The fix is easy - use require('should/as-function')
instead, which will avoid mutating the Object prototype.
Will send a fix out shortly...
We could:
I'd like to do a conversion from 2.0 to 3.0., but I'm having trouble figuring out how to use this repo because there are no installation instructions.
I'm assuming this is an npm package that I can install via npm install -g swagger2openapi
and that command runs but then it doesn't become a recognized command on my mac terminal. I can't tell if that's an issue on my machine or if the repo was never intended to function this way.
Can you provide basic beginners installation instructions? ❤️
In the commit 9155cd4 conversion of x-discriminator
was introduced.
In it you an see that in order for a reference to be resolved successfully, it needs to start with #/definitions/
.
We have a pretty big Swagger file, which is split into several files and there the references almost never start with that.
I have put a reproduction case into a gist: https://gist.github.com/leonardehrenfried/6615e92e818e3f7b22690db7ad237137
I'm hoping that helps diagnosing the issue.
Would it maybe be possible to replace the ref check with a contains("/#")
?
When running convertFile
over (a local clone of) https://github.com/Azure/azure-rest-api-specs/blob/master/arm-apimanagement/2016-10-10/swagger/apimnetworkstatus.json#L49, I get
Error: Could not resolve reference ./apimanagement.json#/parameters/SubscriptionIdParameter
Ideally (from our perspective 😄) those references would be converted blindly, i.e. without touching the external file, but converting the #/...
part assuming that the external file undergoes the same conversion.
I see things like common.resolveExternal
if resolve
is activated (which throws another Error for me), but also that looks as if it would touch the external file. I'd love to contribute, but wanted to hear your side of the story, maybe there is already something in place I'm unaware of. 🙂
JSON Reference RFC defines an order for resolving & encoding key values in a reference. e.g. a/b
should be addressed as a~1b
. The validator fails to resolve these edge cases, preventing /some/path
from being a valuid $ref.
The validator fails to resolve ~1
in references correctly, such that the following example fails:
openapi.yml
paths:
"/":
$ref: "endpoints/foo.yml#/paths/~1"
'/{id}':
$ref: "endpoints/foo.yml#/paths/~1{id}"
endpoints/foo.yml:
paths:
'/':
get:
responses:
'200':
... ... ... and so on ... ... ...
In the above example, the validator incorrectly fails with:
Failed OpenAPI3 schema validation: [
{
"keyword": "type",
"dataPath": "/paths/~1",
"schemaPath": "#/type",
"params": {
"type": "object"
},
"message": "should be object",
RFC 6901 defines a JSON Reference. Specifically (from section 5.):
For example, given the JSON document
{ "foo": ["bar", "baz"], "": 0, "a/b": 1, }
The following JSON strings evaluate to the accompanying values:
"" // the whole document "/foo" ["bar", "baz"] "/foo/0" "bar" "/" 0 "/a~1b" 1
3.1.1
to 3.1.2
.This version is covered by your current version range and after updating it in your project the build failed.
webpack-cli is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 17 commits.
795ac48
v0.1.2
8225339
chore: v.3.1.2>
fb6945b
Merge pull request #618 from webpack/fix/watch-info
99f5a69
Merge pull request #616 from rishabh3112/patch-4
4cba51d
Merge pull request #615 from rishabh3112/patch-3
d4e1614
fix: replace test regex
f3a225a
docs(readme): update webpack-cli to webpack CLI
9aed0dc
fix(tapable): fix hook options
dc4ded9
docs(init): update headers
747aef9
docs(readme): change addons to scaffolds
f8187f1
docs(readme): update links
2ccf9a9
docs(init): update init documentation
3844671
docs(readme): update README.md (#614)
da05c2f
docs(readme): update Readme based on feedback
93ebcc2
chore(docs): update readme
There are 17 commits in total.
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
I would like to use swagger2openapi for validation of my OpenAPI 3 yaml files in our build process. When I run it on an invalid input file I get the expected error message on STDERR, but the exit code is zero. It would be much easier to detect invalid files if the exit code was non-zero.
bash-3.2$ swagger2openapi swagger.yaml
(node:13188) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 2): Error: (Patchable) info object is mandatory
(node:13188) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
bash-3.2$ echo $?
0
(Also the actual error message is buried in the UnhandledPromiseRejectionWarning which isn't ideal. It would be nice to get rid of those unhandled promise warnings.)
I found the tool while looking for a good way to convert our Swagger 2.0 files to OpenAPI 3. The awesome-openapi3 list helped.
Thanks.
4.19.1
to 4.20.0
.This version is covered by your current version range and after updating it in your project the build failed.
webpack is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 40 commits.
c4d8a3c
4.20.0
1495b33
Merge pull request #8070 from chuckdumont/work
434ced3
Merge pull request #8071 from timneutkens/fix/typo
2671d88
Fix typo
f8877e0
Uncaught exception from renderers
31d735c
Merge pull request #8068 from webpack/feature/json-to-typescript
762b1c9
move json-schema-to-typescript to devDependencies
9c8f304
Merge pull request #8065 from webpack/ci/appveyor
3b6d149
Merge pull request #7232 from webpack/feature/json-to-typescript
61718d4
Merge pull request #8064 from xtuc/chore-bump-webassemblyjs13
f8bc251
Reduce the appveyor CI tasks
62b6142
fix Validation test
c768182
fix issues with absolutePath, allOf and anyOf
8c31f2a
fixes for RegExp in schema
44955b7
emit exit code only in lint mode
There are 40 commits in total.
See the full diff
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
Hi,
I have cloned project swagger2openapi, and trying to run the existing file(Before validating my openapi spec) from the repo using given commands.
For example:
Running from command line
swagger2openapi --version ./test/validate/extrnal-docs-no-servers/openapi.yaml
This throws: Microsoft JScript Compilation Error- Code:800A03F6 (Same for all other files)
As list of all supported versions not mentioned on webpage, would like to know/confirm, does this require any specific version of node, npm or what?
Currently, I am using latest versions:
node: 10.3.0
npm: 6.1.0
Thanks,
Hiral
Converting from Swagger 1.x to Swagger 2.0 using one of the existing converters is not lossless. Converting direct from v1.x to OpenAPI 3.0.x would preserve more of the original definition, e.g. multiple basePaths being converted into path- or operation-level servers
arrays.
If you are interested in sponsoring the work to add Swagger 1.x conversion, please comment here or email me.
I have tried the following:
const converter = require('swagger2openapi');
let api = {
swagger: "2.0"
}
converter.convertObj(JSON.stringify(api), opts, function (err, options) {
console.log(options);
console.log(err);
});
The following is returned:
undefined
Error: Unsupported swagger/OpenAPI version: undefined
at /Users/nicu.listana/Work/open-api-transform/open-api-transform-js/node_modules/swagger2openapi/index.js:1158:27
at new Promise (<anonymous>)
at Object.convertObj (/Users/nicu.listana/Work/open-api-transform/open-api-transform-js/node_modules/swagger2openapi/index.js:1127:28)
at Object.<anonymous> (/Users/nicu.listana/Work/open-api-transform/open-api-transform-js/index.js:18:17)
at Module._compile (module.js:635:30)
at Object.Module._extensions..js (module.js:646:10)
at Module.load (module.js:554:32)
at tryModuleLoad (module.js:497:12)
at Function.Module._load (module.js:489:3)
at Function.Module.runMain (module.js:676:10)
at startup (bootstrap_node.js:187:16)
at bootstrap_node.js:608:3
I am not sure what I pass for the first parameter of the convertObj
method.
widdershins
Aloah,
I currently try to convert my Swagger v2 Model definition into OpenApi Specification v3.
I used https://openapi-converter.herokuapp.com/ to transform my file into v3.
After checking some values it appears parameters in formData with type file are not converted into OAS format. (see update 1)
In my specification file I have the following parameter definition
parameters:
- name: "file"
in: "formData"
description: "Attachment file"
required: false
type: "file"
After conversion this parameter has disappeared.
I would have expect something like
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
description: 'Attachment File'
type: string
format: binary
Is it my interpretation of OAS v3 is wrong or a missing translation ?
Thanks in advance.
NB: For testing purpose:
swagger-content.txt
oas-content.txt
Update 1:
After some investigation it appears the work is good if there's no other multipart than the file.
But
The translation is wrong if the multipart request contains a file attachment + others simple parameters (which is the case in my example)
Thanks for the excellent work !
To see what happens to your code in Node.js 10, Greenkeeper has created a branch with the following changes:
.travis.yml
If you’re interested in upgrading this repo to Node.js 10, you can open a PR with these changes. Please note that this issue is just intended as a friendly reminder and the PR as a possible starting point for getting your code running on Node.js 10.
Greenkeeper has checked the engines
key in any package.json
file, the .nvmrc
file, and the .travis.yml
file, if present.
engines
was only updated if it defined a single version, not a range..nvmrc
was updated to Node.js 10.travis.yml
was only changed if there was a root-level node_js
that didn’t already include Node.js 10, such as node
or lts/*
. In this case, the new version was appended to the list. We didn’t touch job or matrix configurations because these tend to be quite specific and complex, and it’s difficult to infer what the intentions were.For many simpler .travis.yml
configurations, this PR should suffice as-is, but depending on what you’re doing it may require additional work or may not be applicable at all. We’re also aware that you may have good reasons to not update to Node.js 10, which is why this was sent as an issue and not a pull request. Feel free to delete it without comment, I’m a humble robot and won’t feel rejected 🤖
There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
Hey Mike,
This issue came in over on Speccy (wework/speccy#119) but I think it's something that will need to take care of in oas-kit.
When given a Schema Object where the type
field is within an anyOf
, the linter reports an error.
Consider the schema:
components:
schemas:
AnyOfExample:
type: object
properties:
intOrFloatProperty:
anyOf:
- type: number
format: float
- type: integer
format: int32
required:
- intOrFloatProperty
The linter reports:
expected Object {
anyOf: Array [
Object { type: 'number', format: 'float' },
Object { type: 'integer', format: 'int32' }
],
... snip ...
} to have property type
anyOf
is an important aspect of JSON Schema, which OAS has adopted. It's a valid part of the specification and should be supported in linters.
Hi,
I'm building a service that has an API catalog. To make the CRUD on API entities, I'm using schema validation with latest version of AJV, which support last JSON schema draft (v6).
I didn't found an official JSON schema for openapi 3.0 spec (I suscribed to this issue to get notified when one is available: OAI/OpenAPI-Specification#1032), so I'm using the one in this repository which seems to be the last up to date.
However, my validator complain and this schema does not seem to be draft v6 compatible. Is it possible to :
"format": "uriref"
with "format": "uri-reference"
$id
property at the root of the schema"exclusiveMinimum": true
with "exclusiveMinimum": 0
and remove "minimum": 0
I can also make a PR if you want, but I have no idea of the $id
to use.
And 👍 for the great work you're doing on the openapi 3 spec !
Upgrading from Swagger 2 to OpenAPI 3 (using swagger2openapi) converts {host, scheme} to a url with ending slash.
When linting the resulting OpenAPI3 against speccy
it complains about a trailing slash.
Probably the end of the line index.js:1284 should not else to '/'
but ''
This is also aligned with https://swagger.io/docs/specification/api-host-and-base-path/
4.20.0
to 4.20.1
.This version is covered by your current version range and after updating it in your project the build failed.
webpack is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
libraryTarget: "amd"
without library nameThere is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot 🌴
As far as I understand from this comment $ref
may be uri-encoded. I'm handling this in ReDoc by using decodeURI
whenever resolving a pointer.
But the following spec crashes when converting with swagger2openapi
:
---
swagger: '2.0'
info:
title: Test
version: ''
paths:
"/test":
get:
responses:
'200':
description: OK
schema:
"$ref": "#/definitions/Def%20with%20space"
definitions:
Def with space:
type: string
with the following error message:
status: false
message: 'Could not resolve reference #/definitions/Def%20with%20space'
Hi Mike:
Validating a contract with something like this:
{
"components": {
"securitySchemes": {
"autentication_jwt": {
"type": "scheme",
"scheme": "bearer",
"bearerFormat": "JWT"
},
...
Got this error:
{
"status": false,
"message": "expected Object { type: 'scheme', scheme: 'bearer', bearerFormat: 'JWT' } not to have property scheme (false negative fail)",
"context": "#/components/securitySchemes/autentication_jwt"
}
Accordingly the Spec, this is a sample with the same info. This should be valid, isn't it?
Repro sample.
Schema validation displays "expected $ref" instead of more helpful "Unexpected field foo
expected a $ref or Schema."
Or rather, "I thought my definition was valid and the error message was unhelpful".
openapi.yml:
...
components:
schemas:
SomeObject:
$ref: 'resources/myobject.yml#/resource/SomeObject'
...
resources/myobject.yml
resource:
SomeObject:
name: SomeObject #Intentionally invalid
type: object #Intentionally Invalid
properties:
Id:
type: string
format: uuid
example: "d2014f64-ffdf-487b-8d12-67a20976aca6"
In this example the name
and type
fields are not part of a SchemaObject and so the validator should logically fail.
components/schema
is expected to be a: Map[string, Schema Object | Reference Object]
(see componentsObject.
In this scenario the validator fails with:
{
"keyword": "required",
"dataPath": "/components/schemas/SomeObject",
"schemaPath": "#/required",
"params": {
"missingProperty": "$ref"
},
"message": "should have required property '$ref'"
...
This is misleading because SomeObject should not have a property $ref; instead, the $ref in components/schema
pointed to an invalid schema.
A better message should either be:
Object at /components/schemas/SomeObject is not a valid schemaObject
or
$ref: 'resources/myobject.yml#/resource/SomeObject'
points to an invalid schema object, schema object expected.
... or some variant.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.