Scriptappy
A specification for Javascript APIs.
Background
In the past few years OpenAPI (formerly Swagger) has become a de-facto standard for describing REST APIs, while a format for non-REST APIs is still lacking.
This is particularly challenging in dynamically typed languages like JavaScript, which despite its popularity still has no consistant way to desribe an API for a consumer.
Various formats do exist though and each project/vendor seem to have their own way of describing their interface:
- The JSON output from the JSDoc3 project comes a long way, but it's primary focus is to generate documentation, not describe the annotated API.
- documentationjs also provides a very good JSON structure, but again the project is more focused on generating documentation.
- esdoc has a very good plugin architecture, outputting a structured JSON should be possible.
- NodeJS has a JSON representation of each one of their modules, e.g. net.html and net.json
Purpose
The purpose of this project is to define and provide a standard for describing JavaScript APIs. By defining a machine-readable format of the consumable API, additional tools can be created based on the specification:
- Generate API reference documentation
- Generate typings (TypeScript, Flow etc.)
- Visualize the API to provide an overview
- Assist in API governance by comparing versions and detecting added/deprecated/removed endpoints
Examples
Current Version
Current version of the Scriptappy specification is 1.0.0
Packages
name | status | description |
---|---|---|
scriptappy-schema | JSON Schema of the scriptappy specification | |
scriptappy-tools | Tools for schema validation | |
scriptappy-from-jsdoc | Generate a scriptappy definition from JSDoc |
- Markdown API reference documentation (coming soon)
- Visualize API (coming soon)
A visual representation of nodejs/scriptappy.json