-
Notifications
You must be signed in to change notification settings - Fork 18
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: add OpenAPI 2.0 JSON parser adapter (#3333)
Refs #3099
- Loading branch information
Showing
30 changed files
with
4,255 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| /dist | ||
| /es | ||
| /cjs | ||
| /types | ||
| /config | ||
| /.nyc_output | ||
| /node_modules | ||
| /**/*.js |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| /dist | ||
| /es | ||
| /cjs | ||
| /types | ||
| /NOTICE | ||
| /swagger-api-apidom-parser-adapter-openapi-json-2-*.tgz |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| { | ||
| "recursive": true, | ||
| "spec": "test/**/*.ts", | ||
| "file": ["test/mocha-bootstrap.cjs"] | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| save-prefix="=" | ||
| save=false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| # @swagger-api/apidom-parser-adapter-openapi-json-2 | ||
|
|
||
| `@swagger-api/apidom-parser-adapter-openapi-json-2` is a parser adapter for the [OpenAPI 2.0 specification](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) in [JSON format](https://www.json.org/json-en.html). | ||
| Under the hood this adapter uses [apidom-parser-adapter-json](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-json) | ||
| to parse a source string into generic ApiDOM in [base ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom#base-namespace) | ||
| which is then refracted with [OpenAPI 2.0 Refractors](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-openapi-2#refractors). | ||
|
|
||
| ## Installation | ||
|
|
||
| After [prerequisites](https://github.com/swagger-api/apidom/blob/main/README.md#prerequisites) for installing this package are satisfied, you can install it | ||
| via [npm CLI](https://docs.npmjs.com/cli) by running the following command: | ||
|
|
||
| ```sh | ||
| $ npm install @swagger-api/apidom-parser-adapter-openapi-json-2 | ||
| ``` | ||
|
|
||
| ## Parser adapter API | ||
|
|
||
| This parser adapter is fully compatible with parser adapter interface required by [@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser#mounting-parser-adapters) | ||
| and implements all required properties. | ||
|
|
||
| ### mediaTypes | ||
|
|
||
| Defines list of media types that this parser adapter recognizes. | ||
|
|
||
| ```js | ||
| [ | ||
| 'application/vnd.oai.openapi;version=2.0', | ||
| 'application/vnd.oai.openapi+json;version=2.0', | ||
| ] | ||
| ``` | ||
|
|
||
| ### detect | ||
|
|
||
| [Detection](https://github.com/swagger-api/apidom/blob/main/packages/apidom-parser-adapter-openapi-json-2/src/adapter.ts#L11) is based on a regular expression matching required OpenAPI 2.0 specification symbols in JSON format. | ||
|
|
||
| ### namespace | ||
|
|
||
| This adapter exposes an instance of [OpenAPI 2.0 ApiDOM namespace](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-openapi-2#openapi-20-namespace). | ||
|
|
||
| ### parse | ||
|
|
||
| `parse` function consumes various options as a second argument. Here is a list of these options: | ||
|
|
||
| Option | Type | Default | Description | ||
| --- | --- | --- | --- | ||
| <a name="specObj"></a>`specObj` | `Object` | [Specification Object](https://github.com/swagger-api/apidom/blob/main/packages/apidom-ns-openapi-2/src/refractor/specification.ts) | This specification object drives the JSON AST transformation to OpenAPI 2.0 ApiDOM namespace. | ||
| <a name="sourceMap"></a>`sourceMap` | `Boolean` | `false` | Indicate whether to generate source maps. | ||
| <a name="refractorOpts"></a>`refractorOpts` | `Object` | `{}` | Refractor options are [passed to refractors](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ns-openapi-2#refractor-plugins) during refracting phase. | ||
|
|
||
| All unrecognized arbitrary options will be ignored. | ||
|
|
||
| ## Usage | ||
|
|
||
| This parser adapter can be used directly or indirectly via [@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser). | ||
|
|
||
| ### Direct usage | ||
|
|
||
| During direct usage you don't need to provide `mediaType` as the `parse` function is already pre-bound | ||
| with [supported media types](#mediatypes). | ||
|
|
||
| ```js | ||
| import { parse, detect } from '@swagger-api/apidom-parser-adapter-openapi-json-2'; | ||
|
|
||
| // detecting | ||
| await detect('{"swagger": "2.0"}'); // => true | ||
| await detect('test'); // => false | ||
|
|
||
| // parsing | ||
| const parseResult = await parse('{"swagger": "2.0"}', { sourceMap: true }); | ||
| ``` | ||
|
|
||
| ### Indirect usage | ||
|
|
||
| You can omit the `mediaType` option here, but please read [Word on detect vs mediaTypes](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser#word-on-detect-vs-mediatypes) before you do so. | ||
|
|
||
| ```js | ||
| import ApiDOMParser from '@swagger-api/apidom-parser'; | ||
| import * as openApiJsonAdapter from '@swagger-api/apidom-parser-adapter-openapi-json-2'; | ||
|
|
||
| const parser = ApiDOMParser(); | ||
|
|
||
| parser.use(openApiJsonAdapter); | ||
|
|
||
| const parseResult = await parser.parse('{"swagger": "2.0"}', { mediaType: openApiJsonAdapter.mediaTypes.latest('json') }); | ||
| ``` |
11 changes: 11 additions & 0 deletions
11
packages/apidom-parser-adapter-openapi-json-2/config/rollup/types.dist.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| import dts from 'rollup-plugin-dts'; | ||
|
|
||
| const config = [ | ||
| { | ||
| input: './types/adapter.d.ts', | ||
| output: [{ file: 'types/dist.d.ts', format: 'es' }], | ||
| plugins: [dts()], | ||
| }, | ||
| ]; | ||
|
|
||
| export default config; |
92 changes: 92 additions & 0 deletions
92
packages/apidom-parser-adapter-openapi-json-2/config/webpack/browser.config.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| import path from 'node:path'; | ||
| import { nonMinimizeTrait, minimizeTrait } from './traits.config.js'; | ||
|
|
||
| const browser = { | ||
| mode: 'production', | ||
| entry: ['./src/adapter.ts'], | ||
| target: 'web', | ||
| performance: { | ||
| maxEntrypointSize: 1800000, | ||
| maxAssetSize: 1800000, | ||
| }, | ||
| output: { | ||
| path: path.resolve('./dist'), | ||
| filename: 'apidom-parser-adapter-openapi-json-2.browser.js', | ||
| libraryTarget: 'umd', | ||
| library: 'apidomParserAdapterOpenApiJson2', | ||
| }, | ||
| resolve: { | ||
| extensions: ['.ts', '.mjs', '.js', '.json'], | ||
| fallback: { | ||
| fs: false, | ||
| path: false, | ||
| }, | ||
| }, | ||
| module: { | ||
| rules: [ | ||
| { | ||
| test: /\.wasm$/, | ||
| loader: 'file-loader', | ||
| type: 'javascript/auto', | ||
| }, | ||
| { | ||
| test: /\.(ts|js)?$/, | ||
| exclude: /node_modules/, | ||
| use: { | ||
| loader: 'babel-loader', | ||
| options: { | ||
| babelrc: true, | ||
| rootMode: 'upward', | ||
| }, | ||
| }, | ||
| }, | ||
| ], | ||
| }, | ||
| ...nonMinimizeTrait, | ||
| }; | ||
|
|
||
| const browserMin = { | ||
| mode: 'production', | ||
| entry: ['./src/adapter.ts'], | ||
| target: 'web', | ||
| performance: { | ||
| maxEntrypointSize: 280000, | ||
| maxAssetSize: 280000, | ||
| }, | ||
| output: { | ||
| path: path.resolve('./dist'), | ||
| filename: 'apidom-parser-adapter-openapi-json-2.browser.min.js', | ||
| libraryTarget: 'umd', | ||
| library: 'apidomParserAdapterOpenApiJson2', | ||
| }, | ||
| resolve: { | ||
| extensions: ['.ts', '.mjs', '.js', '.json'], | ||
| fallback: { | ||
| fs: false, | ||
| path: false, | ||
| }, | ||
| }, | ||
| module: { | ||
| rules: [ | ||
| { | ||
| test: /\.wasm$/, | ||
| loader: 'file-loader', | ||
| type: 'javascript/auto', | ||
| }, | ||
| { | ||
| test: /\.(ts|js)?$/, | ||
| exclude: /node_modules/, | ||
| use: { | ||
| loader: 'babel-loader', | ||
| options: { | ||
| babelrc: true, | ||
| rootMode: 'upward', | ||
| }, | ||
| }, | ||
| }, | ||
| ], | ||
| }, | ||
| ...minimizeTrait, | ||
| }; | ||
|
|
||
| export default [browser, browserMin]; |
32 changes: 32 additions & 0 deletions
32
packages/apidom-parser-adapter-openapi-json-2/config/webpack/traits.config.js
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| import webpack from 'webpack'; | ||
| import TerserPlugin from 'terser-webpack-plugin'; | ||
|
|
||
| export const nonMinimizeTrait = { | ||
| optimization: { | ||
| minimize: false, | ||
| usedExports: false, | ||
| concatenateModules: false, | ||
| }, | ||
| }; | ||
|
|
||
| export const minimizeTrait = { | ||
| plugins: [ | ||
| new webpack.LoaderOptionsPlugin({ | ||
| minimize: true, | ||
| }), | ||
| ], | ||
| optimization: { | ||
| minimizer: [ | ||
| new TerserPlugin({ | ||
| terserOptions: { | ||
| compress: { | ||
| warnings: false, | ||
| }, | ||
| output: { | ||
| comments: false, | ||
| }, | ||
| }, | ||
| }), | ||
| ], | ||
| }, | ||
| }; |
12 changes: 12 additions & 0 deletions
12
packages/apidom-parser-adapter-openapi-json-2/declaration.tsconfig.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| { | ||
| "extends": "./tsconfig.json", | ||
| "exclude": [ | ||
| "test/**/*" | ||
| ], | ||
| "compilerOptions": { | ||
| "declaration": true, | ||
| "declarationDir": "types", | ||
| "noEmit": false, | ||
| "emitDeclarationOnly": true | ||
| } | ||
| } |
Oops, something went wrong.