cdwv / oas3-api-snippet-enricher

Enrich your OpenAPI 3.0 JSON with code samples

Enrich your OpenAPI 3.0 schema with examples

Thanks to the wonderful swagger-snippet module you can now simply enrich your OpenAPI schema with code samples. It's as easy as 1.2.3.

1. npm install snippet-enricher-cli
2. ./node_modules/.bin/snippet-enricher-cli --input=your_oas.json

Example Usage

Enrich your OAS 3.0 Schema

./node_modules/.bin/snippet-enricher-cli --input=openapi.json > openapi-with-examples.json

Alternatively you can point it to a YAML-formatted spec:

curl https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml --output petstore.yaml
./node_modules/.bin/snippet-enricher-cli --input=petstore.yaml > openapi-with-examples.json

Use targets options to specific languages:

./node_modules/.bin/snippet-enricher-cli --targets="node_request,shell_curl" --input=openapi.json > openapi-with-examples.json

Use ReDoc to build beautiful API doc:

redoc-cli bundle openapi-with-examples.json

enjoy.

Contributing

Contributions are most welcome!

License

MIT

Maintainers

Project is currently maintained, in our spare time, by codewave.eu and a growing number of Contributors!

oas3-api-snippet-enricher's Issues

How to handle {}

In the OpenAPI spec we use

'/lists/v2/audiences/{audienceId}':
   GET: ....

This results in the examples

curl --request GET \
  --url https://example.com/lists/v2/audiences/%7BaudienceId%7D \
  --header 'X-ApiKey: REPLACE_KEY_VALUE'

The {} get transformed in the %7B %7D while we would expect https://example.com/lists/v2/audiences/{audienceId}

Am I doing something wrong or have I missed a configuration parameter?

Skip custom properties

I am using openapi-filter to filter some paths, due to which methods have invalid boolean properties and this error is thrown:

TypeError: Cannot create property 'x-codeSamples' on boolean 'true'
    at enrichSchema (/Users/rohitgohri/.npm/_npx/85039/lib/node_modules/snippet-enricher-cli/index.js:19:48)
    at Object.<anonymous> (/Users/rohitgohri/.npm/_npx/85039/lib/node_modules/snippet-enricher-cli/index.js:40:12)
    at Module._compile (internal/modules/cjs/loader.js:956:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:973:10)
    at Module.load (internal/modules/cjs/loader.js:812:32)
    at Function.Module._load (internal/modules/cjs/loader.js:724:14)
    at Module.require (internal/modules/cjs/loader.js:849:19)
    at require (internal/modules/cjs/helpers.js:74:18)
    at Object.<anonymous> (/Users/rohitgohri/.npm/_npx/85039/lib/node_modules/snippet-enricher-cli/bin/snippet-enricher-cli:2:1)
    at Module._compile (internal/modules/cjs/loader.js:956:30)

If we could skip x- properties in the loop this will be fixed.

Upgrade `openapi-snippet` dependency to latest version

Issue Description

The snippet-enricher-cli library currently depends on the openapi-snippet library version ^0.9.0. However, the latest version of openapi-snippet is 0.14.0 (at the time of writing this issue), which may include bug fixes, performance improvements, or new features.

It is recommended to upgrade the openapi-snippet dependency to the latest version to ensure that the snippet-enricher-cli library is using the most recent and stable version of the dependency.

Upload to NPM

It is possible to upload this package to NPM?

Its nice to use the snippet generator as a CLI interface for integration with build tools.

Thanks!

Add Ruby support

Adding ruby to the targets array generates Ruby code snippets. Tested it on Mac and Ubuntu. Code:

'use strict';

const fs = require('fs');
const OpenAPISnippet = require('openapi-snippet');
const yaml = require('js-yaml');
const args = require('yargs').argv;

let targets = ['node_request','shell_curl', 'shell_httpie', 'python_python3', 'php_curl', 'php_http1', 'php_http2', 'ruby'];

if (args.targets) {
	targets = args.targets.split(',');
}

function enrichSchema(schema){
	for(var path in schema.paths){
		for(var method in schema.paths[path]){
			var generatedCode = OpenAPISnippet.getEndpointSnippets(schema, path, method, targets);
			schema.paths[path][method]["x-codeSamples"] = [];
			for(var snippetIdx in generatedCode.snippets){
				var snippet = generatedCode.snippets[snippetIdx];
				schema.paths[path][method]["x-codeSamples"][snippetIdx] = { "lang": snippet.title, "source": snippet.content };
			}
		}
	}
	return schema;
}

if(!args.input){
	throw new Error("Please pass the OpenAPI JSON schema as argument.");
}

// Try to interpret as YAML first, based on file extension
if(args.input.indexOf('yml') !== -1 || args.input.indexOf('yaml') !== -1){
	try {
		let schema = yaml.safeLoad(fs.readFileSync(args.input, 'utf8'));
		schema = enrichSchema(schema);
		console.log(JSON.stringify(schema));
	} catch (e) {
		console.log(e);
	}
} else {
	fs.readFile(args.input, (err, data) => {
		if (err) throw err;
		let schema = JSON.parse(data);
		schema = enrichSchema(schema);
		console.log(JSON.stringify(schema));
	});
}

TypeError: Cannot create property 'x-codeSamples' on string 'paths/pets.yaml'

👋 Hello!

Trying this out for the first time. I rearranged the expanded petstore example to have...

paths:
  /pets:
    $ref: paths/pets.yaml

Here is the directory for the rearranged petstore example.

👉 petstore.zip

When I run ./node_modules/.bin/snippet-enricher-cli --input=petstore/openapi.yaml > openapi-with-examples.json

I open up openapi-with-examples.json and it contains the following...

TypeError: Cannot create property 'x-codeSamples' on string 'paths/pets.yaml'
    at enrichSchema ({MY_LOCAL_PATH}/node_modules/snippet-enricher-cli/index.js:19:48)
    at Object.<anonymous> ({MY_LOCAL_PATH}/node_modules/snippet-enricher-cli/index.js:40:12)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1155:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Module.require (node:internal/modules/cjs/loader:1005:19)
    at require (node:internal/modules/cjs/helpers:102:18)
    at Object.<anonymous> ({MY_LOCAL_PATH}/node_modules/snippet-enricher-cli/bin/snippet-enricher-cli:2:1)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)

🤔 Does this not work on refs? Does the openapi.yaml need to be a single file?

Code samples do not generate parameters for multipart/form-data

When doing this

requestBody:
    content:
      multipart/form-data:

Instead of this

requestBody:
    content:
      application/json:

Specified fields from the schema are not generated in the code samples

E.g. all I get is this, with no fields:

curl --request POST \
  --url $URL \
  --header 'content-type: multipart/form-data'

Error when secDefinition does not exists

When you parse OAS3 files without secDefintion.scheme, the script will fail. Opeapi-to-har expects a scheme.

 authScheme = secDefinition.scheme.toLowerCase();
                                          ^
TypeError: Cannot read property 'toLowerCase' of undefined
at getHeadersArray (/node_modules/openapi-snippet/openapi-to-har.js:287:43)
    at Object.createHar [as getEndpoint] (//node_modules/openapi-snippet/openapi-to-har.js:44:14)
    at Object.getEndpointSnippets (/node_modules/openapi-snippet/index.js:31:28)
    at enrichSchema (/node_modules/snippet-enricher-cli/index.js:18:39)
    at fs.readFile (node_modules/snippet-enricher-cli/index.js:52:12)
    at FSReqWrap.readFileAfterClose [as oncomplete] (internal/fs/read_file_context.js:53:3)

Error during installation with node:alpine docker image

Hi,
I get an error when I try to install your npm package.
That's my node image:
FROM node:12.16.2-alpine3.11

Here the log file
2020-05-01T20_27_36_369Z-debug.log

Require(...) is not a function

When (as documented) running ./node_modules/.bin/snippet-enricher-cli --input=.... there is an error:

require('./../index.js')(); ^ TypeError: require(...) is not a function

Removing the () from the require fixed this issue.

URL should match format "uri"

Hi,

I try to enrich a JSON generated file that is in a valid openapi JSON format and properly renders in Redoc.

But still I get this error:

[Error [HARError]: validation failed] {
  errors: [
    {
      keyword: 'format',
      dataPath: '.url',
      schemaPath: '#/properties/url/format',
      params: { format: 'uri' },
      message: 'should match format "uri"'
    }
  ]
}

It is clear that there is something wrong with the URL, but I have no idea where to look.

Could you point in the right direction? Or is there an option to show more detailed debug output?

Make Languages a CLI option

It would be nice to specify which languages to generate snippets for customization via the CLI.

Something like

node index.js --targets="python, shell_curl" openapi.json > openapi-with-examples.json