JsonSchema: true // Treat $ref like JSON Schema and convert to OpenAPI Schema Objects Resolve: true, // Resolve external references For example: const loader = require('speccy/lib/loader') The loader object will return a promise that resolves to an object containing Not just a command line tool, speccy can be used to normalize machine-readable specifications. # Output a lot of information about what is happening (wont work if you have quiet on) CreateĪ speccy.yaml in the root of your project.Įxample: # Convert JSON Schema-proper to OpenAPI-flavoured Schema Objects To avoid needing to send command line options and switches every time, a config file can be used. h, -help output usage information Config File p, -port port on which the server will listen (default: 5000) View specifications in beautiful human readable documentation In the future we'll have speccy outlining improvements right in here, but one thing at a time. Using ReDoc, speccy can offer a preview of your specifications, in human-readable format. Thanks to the -json-schema switch, you can have an OpenAPI file which $refs JSON Schema files (not just OpenAPI-flavoured JSON Schema), then resolve them all into one real OpenAPI file, thanks to wework/json-schema-to-openapi-schema. It avoid cyclical dependencies (when A has a property that $refs A, which in turn destroys your CPU), and all sorts of other things. Starting with the fantastic resolver logic form swagger2openapi, speccy has one of the most robust Pull in external $ref files to create one mega-file By default it will output to stdout, but you can pass -o with a file name to write the file locally. Resolving $ref is the art of taking multiple files and squashing them all down into one big OpenAPI file. There are strict rules which demand more contact details, "real" domains, a license, and requires tags have a description! Resolve Command There are going to be different things people are interested in, so the default rules suggest things we think everyone should do adding descriptions to parameters and operations, and having some sort of contact info. You'll see output such as: #/info R: info-contact D: info object should contain contact object v, -verbose set verbosity (use multiple times to increase level) j, -json-schema treat $ref like JSON Schema and convert to OpenAPI Schema Objects Usage: lint Įnsure specs are not just valid OpenAPI, but lint against specified rules "Bad" is subjective, but you'll see validation errors, along with special rules for making your APIs better. The goal here is to sniff your files for potentially bad things. Serve view specifications in beautiful human readable documentation Lint Command Resolve pull in external $ref files to create one mega-file Lint ensure specs are not just valid OpenAPI, but lint against specified rules
c, -config config file (containing JSON/YAML).
#Use speccy install
$ npm install speccy -gĪlternatively, you can use it with Docker (see "Using Docker" below.) Usage Usage: speccy You can install this node module via NPM or Yarn. If you want to run speccy on OpenAPI (f.k.a Swagger) v2.0 specs, run it through swagger2openapi first and speccy can give advice on the output. Taking off from where Mike Ralphson started with linting in swagger2openapi, Speccy aims to become the rubocop or eslint of OpenAPI. Make sure your OpenAPI 3.0 specifications are more than just valid, make sure they're useful!
0 kommentar(er)
