Skip to content

Latest commit

 

History

History
52 lines (35 loc) · 3.05 KB

README.md

File metadata and controls

52 lines (35 loc) · 3.05 KB

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.1.0

Packages

name status description
scriptappy-schema scriptappy-schema-status JSON Schema of the scriptappy specification
scriptappy-from-jsdoc scriptappy-from-jsdoc-status Generate a scriptappy definition from JSDoc
  • Markdown API reference documentation (coming soon)
  • Visualize API (coming soon) Visual API

    A visual representation of nodejs/scriptappy.json