swagger-md

Converts Swagger API spec to Markdown format.

Usage

Install NPM module:

npm install swagger-md

Convert Swagger API spec to Markdown format:

1import swagger_md from 'swagger-md';
2import swagger_spec from './swagger-api-spec.json';
3
4function responseExampleProvider(path, method) {
5  return [
6    '```json',
7    '{ "foo": 1 }',
8    '```',
9  ].join('\n');
10} 
11
12swagger_md.convertToMarkdown(swagger_spec, { response_example_provider: responseExampleProvider }).then(markdown_str => {
13  // Use markdown_str, e.g. write to "api.md"
14});

1// It is also possible to pass a path to the root file of the API spec (can be json or yaml) and supports local file refs.
2const path_to_spec = 'path/to/api-spec.json';
3
4swagger_md.convertToMarkdown(path_to_spec).then(markdown_str => {
5  // refs to other local files are resolved and the markdown contains the entire API
6});

resolveApiSpec resolves the API spec in the same way as convertToMarkdown but returns the resolved object without converting it to markdown

1const path_to_spec = 'path/to/api-spec.json';
2const options = {
3  // optionally specify that external refs should be fetched and resolved
4  external: true
5};
6
7swagger_md.resolveApiSpec(path_to_spec, options).then(spec => {
8  // spec == the resolved API spec
9});

To use the swagger-md in a CommonJS module environment the usage statement should look like:

1var swagger_md = require('swagger-md').default;
2...

What can it do?

See ./test-fixtures/swagger for examples of a swagger.json converted to Markdown.

Want it do handle more? Feel free to contribute!

Contributing

1. Write a new test with new fixtures or extend the existing ones
2. Make a PR
3. :pray: :clap: