├── .gitignore ├── LICENSE ├── README.md ├── bin ├── snippet-enricher └── snippet-enricher-cli ├── cdwv-logo-new.svg ├── image.png ├── index.js └── package.json /.gitignore: -------------------------------------------------------------------------------- 1 | /.idea -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 CodeWave 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Enrich your OpenAPI 3.0 schema with examples 2 | 3 | Thanks to the wonderful [swagger-snippet](https://github.com/ErikWittern/swagger-snippet) module you can now simply enrich your OpenAPI schema with code samples. It's as easy as 1.2.3. 4 | 5 | 1. ``npm install snippet-enricher-cli`` 6 | 2. ``./node_modules/.bin/snippet-enricher-cli --input=your_oas.json`` 7 | 8 | ## Example Usage 9 | 10 | Enrich your OAS 3.0 Schema 11 | ``` 12 | ./node_modules/.bin/snippet-enricher-cli --input=openapi.json > openapi-with-examples.json 13 | ``` 14 | Alternatively you can point it to a YAML-formatted spec: 15 | ``` 16 | curl https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml --output petstore.yaml 17 | ./node_modules/.bin/snippet-enricher-cli --input=petstore.yaml > openapi-with-examples.json 18 | ``` 19 | 20 | Use targets options to specific languages: 21 | ``` 22 | ./node_modules/.bin/snippet-enricher-cli --targets="node_request,shell_curl" --input=openapi.json > openapi-with-examples.json 23 | ``` 24 | 25 | Use [ReDoc](https://github.com/Redocly/redoc/) to build beautiful API doc: 26 | ``` 27 | redoc-cli bundle openapi-with-examples.json 28 | ``` 29 | 30 | enjoy. 31 | 32 | ![ReDoc API documentation with code samples](image.png) 33 | 34 | Contributing 35 | ======================================================================= 36 | 37 | Contributions are most welcome! 38 | 39 | 40 | License 41 | ======================================================================= 42 | 43 | MIT 44 | 45 | Maintainers 46 | =========== 47 | 48 | [

](http://codewave.eu) 49 | 50 | Project is currently maintained, in our spare time, by [codewave.eu](http://codewave.eu) and a growing number of Contributors! 51 | -------------------------------------------------------------------------------- /bin/snippet-enricher: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | require('./../index.js'); 3 | -------------------------------------------------------------------------------- /bin/snippet-enricher-cli: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | require('./../index.js'); 3 | -------------------------------------------------------------------------------- /cdwv-logo-new.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 140 | -------------------------------------------------------------------------------- /image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cdwv/oas3-api-snippet-enricher/60cec08e5f728e5d674505afeb3ead4ddb9bc9c6/image.png -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const fs = require('fs'); 4 | const OpenAPISnippet = require('openapi-snippet'); 5 | const yaml = require('js-yaml'); 6 | const args = require('yargs').argv; 7 | 8 | let targets = ['node_request','shell_curl', 'shell_httpie', 'python_python3', 'php_curl', 'php_http1', 'php_http2']; 9 | 10 | if (args.targets) { 11 | targets = args.targets.split(','); 12 | } 13 | 14 | function enrichSchema(schema){ 15 | for(var path in schema.paths){ 16 | 17 | for(var method in schema.paths[path]){ 18 | if ( !/get|put|post|delete|patch|options|head|trace/.test(method)) { continue; } 19 | var generatedCode = OpenAPISnippet.getEndpointSnippets(schema, path, method, targets); 20 | schema.paths[path][method]["x-codeSamples"] = []; 21 | for(var snippetIdx in generatedCode.snippets){ 22 | var snippet = generatedCode.snippets[snippetIdx]; 23 | schema.paths[path][method]["x-codeSamples"][snippetIdx] = { "lang": snippet.title, "source": snippet.content }; 24 | } 25 | 26 | } 27 | } 28 | return schema; 29 | } 30 | 31 | if(!args.input){ 32 | throw new Error("Please pass the OpenAPI JSON schema as argument."); 33 | } 34 | 35 | // Try to interpret as YAML first, based on file extension 36 | 37 | if(args.input.indexOf('yml') !== -1 || args.input.indexOf('yaml') !== -1){ 38 | try { 39 | 40 | let schema = yaml.safeLoad(fs.readFileSync(args.input, 'utf8')); 41 | schema = enrichSchema(schema); 42 | console.log(JSON.stringify(schema)); 43 | } catch (e) { 44 | // Do something with this 45 | console.log(e); 46 | } 47 | 48 | } else { 49 | 50 | fs.readFile(args.input, (err, data) => { 51 | if (err) throw err; 52 | let schema = JSON.parse(data); 53 | schema = enrichSchema(schema); 54 | console.log(JSON.stringify(schema)); 55 | }); 56 | 57 | } 58 | 59 | 60 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "snippet-enricher-cli", 3 | "version": "0.0.6", 4 | "description": "Enrich OpenAPI 3.0 JSON with code snippets (``x-codeSamples``)", 5 | "repository": { 6 | "type": "git", 7 | "url": "https://github.com/cdwv/oas3-api-snippet-enricher" 8 | }, 9 | "main": "index.js", 10 | "bin": { 11 | "snippet-enricher-cli": "bin/snippet-enricher-cli" 12 | }, 13 | "scripts": { 14 | "test": "echo \"Error: no test specified\" && exit 1" 15 | }, 16 | "keywords": [ 17 | "openapi", 18 | "swagger", 19 | "oas3" 20 | ], 21 | "author": "Andrzej WP", 22 | "license": "MIT", 23 | "dependencies": { 24 | "js-yaml": "^3.13.1", 25 | "openapi-snippet": "^0.9.0", 26 | "yargs": "^15.3.1" 27 | } 28 | } 29 | --------------------------------------------------------------------------------