1 | # swagger2openapi
|
2 |
|
3 | ![logo](https://github.com/Mermade/oas-kit/blob/master/docs/logo.png?raw=true)
|
4 |
|
5 | [![OpenAPI Validation](https://mermade.org.uk/openapi-converter/api/v1/badge?url=https://mermade.org.uk/openapi-converter/examples/openapi.json)](https://mermade.org.uk/openapi-converter/api/v1/validate?url=https://mermade.org.uk/openapi-converter/examples/openapi.json)
|
6 | ![Build](https://img.shields.io/travis/Mermade/oas-kit/master.svg)
|
7 | [![Tested on APIs.guru](https://api.apis.guru/badges/tested_on.svg)](https://APIs.guru)
|
8 | [![Tested on Mermade OpenAPIs](https://img.shields.io/badge/Additional%20Docs-74426-brightgreen.svg)](https://github.com/mermade/openapi-definitions)
|
9 | [![Coverage Status](https://coveralls.io/repos/github/Mermade/swagger2openapi/badge.svg?branch=master)](https://coveralls.io/github/Mermade/swagger2openapi?branch=master)
|
10 | [![Known Vulnerabilities](https://snyk.io/test/npm/swagger2openapi/badge.svg)](https://snyk.io/test/npm/swagger2openapi)
|
11 | [![Greenkeeper badge](https://badges.greenkeeper.io/Mermade/oas-kit.svg)](https://greenkeeper.io/)
|
12 |
|
13 | Convert Swagger 2.0 definitions into OpenApi 3.0.x
|
14 |
|
15 | The online version of the converter/validator runs on a [Linode](https://www.linode.com/?r=5734be467cc501b23267cf66d451bc339042ddfa) VPS. If you are considering a hosted server, please sign up through this link so we both receive free credit.
|
16 |
|
17 | Currently tracking [v3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)
|
18 |
|
19 | ## Installation:
|
20 | This is a node.js module, which you can run on the command line. First ensure you have npm installed (tested on version 6.1+), and then install as follows:
|
21 | ```bash
|
22 | npm install -g swagger2openapi
|
23 | ```
|
24 | Or, add it to your node.js projects as shown below in option B.
|
25 |
|
26 | ## Usage:
|
27 | ### A. Command line:
|
28 |
|
29 | ```text
|
30 | swagger2openapi [options] [filename|url]
|
31 | Options:
|
32 | --refSiblings mode to handle $ref's with sibling properties
|
33 | [choices: "remove", "preserve", "allOf"]
|
34 | --resolveInternal resolve internal references also [boolean]
|
35 | --warnProperty Property name to use for warning extensions
|
36 | [string] [default: "x-s2o-warning"]
|
37 | --version Show version number [boolean]
|
38 | -c, --components output information to unresolve a definition [boolean]
|
39 | -d, --debug enable debug mode, adds specification-extensions[boolean]
|
40 | -e, --encoding encoding for input/output files[string] [default: "utf8"]
|
41 | -f, --fatal make resolution errors fatal [boolean]
|
42 | -h, --help Show help [boolean]
|
43 | -i, --indent JSON indent to use, defaults to 4 spaces [string]
|
44 | -o, --outfile the output file to write to [string]
|
45 | -p, --patch fix up small errors in the source definition [boolean]
|
46 | -r, --resolve resolve external references [boolean]
|
47 | -t, --targetVersion override default target version of 3.0.0 [string]
|
48 | -u, --url url of original spec, creates x-origin entry [string]
|
49 | -v, --verbose increase verbosity [count]
|
50 | -w, --warnOnly Do not throw on non-patchable errors, add warning
|
51 | extensions [boolean]
|
52 | -y, --yaml write YAML, default JSON (overridden by --outfile
|
53 | filepath extension) [boolean]
|
54 | -b, --rbname Extension to use to preserve body parameter names in
|
55 | converted operations ("" == disabled)
|
56 | [string] [default: ""]
|
57 | ```
|
58 |
|
59 | ### B. Node.js API:
|
60 |
|
61 | ```javascript
|
62 | const converter = require('swagger2openapi');
|
63 | let options = {};
|
64 | //options.patch = true; // fix up small errors in the source definition
|
65 | //options.warnOnly = true; // Do not throw on non-patchable errors
|
66 | converter.convertObj(swagger, options, function(err, options){
|
67 | // options.openapi contains the converted definition
|
68 | });
|
69 | // also available are asynchronous convertFile, convertUrl, convertStr and convertStream functions
|
70 | // if you omit the callback parameter, you will instead receive a Promise
|
71 | ```
|
72 |
|
73 | Note that the `options` object passed in is modified/extended by the `convert*` functions.
|
74 |
|
75 | See the [boast command-line tool](./boast.js) for a fuller CLI tool for converting, validating and linting.
|
76 |
|
77 | See here for complete [documentation](/docs/options.md) of the `options` object.
|
78 |
|
79 | ### C. Browser:
|
80 |
|
81 | Or use the [online version](https://mermade.org.uk/openapi-converter) which also includes its own [API](http://petstore.swagger.io/?url=https://mermade.org.uk/openapi-converter/contract/swagger.json).
|
82 |
|
83 | #### Browser Support
|
84 |
|
85 | See [initial documentation](/docs/browser.md).
|
86 |
|
87 | ## Features
|
88 |
|
89 | ### OpenAPI 3.0.x validation
|
90 |
|
91 | `oas-validate` can be used as a validator if given one or more existing OpenAPI 3.x definitions. The validator (however it is called) uses [WHATWG](https://whatwg.org/) URL parsing if available (node 7.x and above). The validator can have a linting mode enabled with the `--lint` option. Rules are defined [here](/packages/oas-linter/rules.yaml). Contributions of rules and rule actions for the linter are very much appreciated.
|
92 |
|
93 | ```text
|
94 | oas-validate.js [options] {path-to-docs}...
|
95 |
|
96 | Options:
|
97 | --lint lint the definition [boolean]
|
98 | --validateSchema Run schema validation step: first, last* or never [string]
|
99 | --warnOnly Do not throw on non-patchable errors [boolean]
|
100 | -h, --help Show help [boolean]
|
101 | --version Show version number [boolean]
|
102 | -e, --encoding encoding for input/output files [string] [default: "utf8"]
|
103 | -f, --fail path to docs expected to fail [string]
|
104 | -j, --jsonschema path to alternative JSON schema [string]
|
105 | -l, --laxurls lax checking of empty urls [boolean]
|
106 | -m, --mediatype check media-types against RFC pattern [boolean]
|
107 | -n, --nopatch do not patch minor errors in the source definition [boolean]
|
108 | -o, --output output conversion result [string] [default: "openapi.yaml"]
|
109 | -q, --quiet do not show test passes on console, for CI [boolean]
|
110 | -r, --resolve resolve external references [boolean]
|
111 | -s, --stop stop on first error [boolean]
|
112 | -v, --verbose increase verbosity [count]
|
113 | -w, --whatwg enable WHATWG URL parsing [boolean]
|
114 | -y, --yaml skip YAML-safe test [boolean]
|
115 | ```
|
116 |
|
117 | ### Reference preservation
|
118 |
|
119 | `swagger2openapi` by default preserves almost all `$ref` JSON references in your API definition, and does not dereference
|
120 | every item, as with some model-based parsers. The exception is internal references within externally referenced documents. To enable internal `$ref` resolution across the whole document, use the `--resolveInternal` option, which also disables creation of `$ref`s for shared `requestBodies`.
|
121 |
|
122 | ### Schema transformations
|
123 |
|
124 | `swagger2openapi` will automatically 'repair' a number of problems where non-compliant Swagger 2.0 schemas have been used. It will attempt to transform JSON schemas (used incorrectly) into OpenAPI 3.0.x Schema objects.
|
125 |
|
126 | ### Specification extensions
|
127 |
|
128 | `swagger2openapi` has support for a limited number of real-world [specification extensions](/docs/extensions.md) which have a direct bearing on the conversion. All other specification extensions are left untouched. swagger2openapi is [swaggerplusplus](https://github.com/mermade/swaggerplusplus)-compatible.
|
129 |
|
130 | It is expected to be able to configure the process of specification-extension modification using options or a plugin mechanism in a future release.
|
131 |
|
132 | ## Tests
|
133 |
|
134 | To run a test-suite:
|
135 |
|
136 | ```shell
|
137 | node oas-validate [-f {path-to-expected-failures}]... [{path-to-APIs|single-file...}]
|
138 | ```
|
139 |
|
140 | The test harness currently expects files with a `.json` or `.yaml` extension, or a single named file, and has been tested on LTS Node.js versions against
|
141 |
|
142 | * [APIs.guru](https://github.com/APIs-guru/openapi-directory)
|
143 | * [Mermade OpenApi specifications collection](https://github.com/mermade/openapi_specifications)
|
144 | * [OpenAPI3-Examples (pass/fail)](https://github.com/mermade/openapi3-examples)
|
145 | * [SOM-Research collection](https://github.com/SOM-Research/hapi)
|
146 |
|
147 | Additionally `swagger2openapi` has been tested on a corpus of 74,426 real-world valid Swagger 2.0 definitions from GitHub and [SwaggerHub](https://swaggerhub.com/). However, if you have a definition which causes errors in the converter or does not pass validation, please do not hesitate to [raise an issue](https://github.com/Mermade/swagger2openapi/issues).
|
148 |
|
149 | ### Regression tests
|
150 |
|
151 | Regression tests (thanks [@domharrington](https://github.com/domharrington)) live in the `/test` directory and can be run with `npx mocha`. Each sub-directory of `s2o-test` should contain an input `swagger.yaml` file, an expected output `openapi.yaml` file and an optional `options.yaml` file. You can put private test cases in sub-directories starting with an underscore character. In the `resolver` sub-directory, each directory should contain an `input.yaml`, an `output.yaml` and an optional `options.yaml` file.
|
152 |
|
153 | ### Version history
|
154 |
|
155 | * [Change-Log](https://github.com/Mermade/oas-kit/blob/master/CHANGELOG.md#change-log)
|
156 |
|
157 | ## License
|
158 |
|
159 | [BSD-3-Clause](LICENSE) except the `openapi-3.0.json` schema, which is taken from the [OpenAPI-Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.yaml) which is licensed under the [Apache-2](http://www.apache.org/licenses/LICENSE-2.0) license.
|