apispecmd-ts

Table of Contents

• About the Project
  • Built on Node.js With
• Usage
  • Install
  • Launch
  • Use as Library
• Docker Image
  • Convert to PDF Using Docker
• Semver
• Contributing
  • Contribution Rules
    • Prettier Rules
  • Contributors
• License

About the Project

apispecmd-ts, as the name suggests, is a library that converts OpenAPI 3.0 specs into human-readable Markdown. This is an opinionated library: the output format, architectural choices and conventions are enforced by the development team to reduce decision burden and code complexity. (Prettier is a good example of opinionated library)

The project is still in initial development phase.

Built on Node.js With

• Jest
• openapi-types
• Swagger Parser
• Typescript
• Winston

Usage

Current Version

The project is currently in official development release, thus the first working version is v0.1.0. No major version has been released yet. Versions prior to v0.1.0 (v0.0.x) are intended for embrional state of this project, their usage is discouraged.

Install

$ npm install @bitacode/apispecmd-ts

Launch With Command Line

$ INPUT_SPEC=/path/to/spec.yaml OUTPUT_MARKDOWN=/path/to/output.md OUTPUT_PDF=/path/to/output.pdf apispecmd-ts

Use as Library

import { convertApiSpecToMd } from '@bitacode/apispecmd-ts'

const markdownContent: string | void = await convertApiSpecToMd('/path/to/spec.yaml')

console.log(markdownContent)

Function signature is:

const convertApiSpecToMd = async (inputSpec: string, outputMarkdown?: string, outputPdf?: string): Promise<string | void>

If no outputMarkdown is specified the output will be a string, as reported in the above example.

If no outputPdf is provided only the markdown output will be generated.

It is not possible to generate only the PDF without markdown.

Docker Image

You can find a fully working Docker image on Dockerhub. You can build the image by yourself using the Dockerfile in this repo.

Convert Using Docker

$ docker run --rm --name apispecmd-ts \
  --volume /path/to/openapi/spec/folder/:/app/input
  --volume /path/to/markdown/output/folder/:/app/output
  --env INPUT_SPEC=input/apispec.yaml \
  --env OUTPUT_MARKDOWN=output/output-markdown.md \
  --env OUTPUT_PDF=output/output-pdf.pdf \ # OPTIONAL
  ccarcaci/apispecmd-ts

Where:

• /path/to/openapi/spec/folder/ points to spec host folder where your apispec.yaml file resides. JSON format is supported too.
• /path/to/markdown/output/folder points to the folder where you want to store your markdown result.
• INPUT_SPEC=input/apispec.yaml "input" part is fixed and apispec.yaml is your spec file name.
• OUTPUT_MARKDOWN=output/output-markdown.md "output" part is fixed and output-markdown.md is the desired name of your markdown output.
• (OPTIONAL) - OUTPUT_PDF=output/output-pdf.pdf "output" part is fixed and output-pdf.pdf is the desired name of your pdf output.

Semver

This project follows the Semver specification for versioning starting from v1.0.0

• Major releases of OpenAPI specification results in major release of the library.
• Notable changes in the output format of Markdown output result in a minor release of the library.

Contributing

This project will not be eagerly maintained, the creator is involved with several other projects, so contibutions are strongy welcome.

To contribute with this repo:

• Fork the project.
• Create your feature branch with the following naming convention. feature/the-new-fancy-feat
• Commit your changes.
• Create a PR.

Contibution Rules

In order to contribute with this project there are some rules to follow.

• Provided code must be covered with unit tests.
• Correct conversion proof must be provided alongside the PR.
• prettier is the code formatting choice for this project.

Prettier Rules

{
  "jsxBracketSameLine": true,
  "jsxSingleQuote": true,
  "printWidth": 120,
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2
}

Contributors

• Claudio Carcaci - Creator

License

Distributed under the MIT License.