@beakyn/specs-editor

Beakyn Specs Editor

Serves Swagger Editor over local spec files and updates on every change.

Table of Contents

• Usage
  • Basic
    • Working on the Specification
    • Adding to an Existing Project
  • Advanced
    • API
      • liveEditorServer(port)
    • CLI
      • $ bkn-specs-editor serve --port
      • $ bkn-specs-editor bundle --destinationPath
• License

Usage

Basic

Working on the Specification

These are the basic steps when working with a repo that uses bkn-specs-editor inside devDependencies.

1. Go the project repository of which the spec you'd like to work on–e.g. Beakyn/gsp-geofence-api.

2. Run the specs editing script–usually npm run docs:specs:edit.

3. A new tab on your browser will open running an instance of the Swagger Editor.

4. Write everything you need. All changes are immediately propagated through the spec/ directory.

5. Once you finish with the changes you can run the bundling script using: npm run docs:specs:build.

6. Share you changes with the rest of the world by pushing to the master branch on GitHub.

Adding to an Existing Project

These are the basic steps when adding bkn-specs-editor to an existing API project documentation workflow.

1. Add it inside devDependencies:

   # Using npm
   npm install --save-dev bkn-specs-editor
   
   # Using yarn
   yarn add --dev bkn-specs-editor

2. Ensure you have the following structure in your project:

   |-- spec/
   |   |-- definitions/
   |   |-- paths/
   |   |-- swagger.yml
   |-- package.json
   |-- ...

3. Add a specs editing script–standarized as npm run docs:specs:edit in your package.json:

   {
     "name": "gsp-geofence-api",
     ...
     "scripts": {
       ...
       "docs:specs:edit": "bkn-specs-editor serve"
     }
     ...
   }

4. Add a bundling script–standarized as npm run docs:specs:build in your package.json:

   {
     "name": "gsp-geofence-api",
     ...
     "scripts": {
       ...
       "docs:specs:edit": "bkn-specs-editor serve",
       "docs:specs:build": "bkn-specs-editor bundle"
     },
     ...
   }

5. You can now start working on the specification.

Advanced

API

# Using npm
npm install bkn-specs-editor

# Using yarn
yarn add bkn-specs-editor

liveEditorServer(port)

Receives:

• port: number

An available port to start listening on (defaults to 3001).

Does: Enables live editing of the Swagger API file on the selected port.

CLI

# Using npm
npm install -g bkn-specs-editor

# Using yarn
yarn add global bkn-specs-editor

$ bkn-specs-editor serve --port

Receives:

• port: number

An available port to start listening on (defaults to 3001).

Does: Enables live editing of the Swagger API file on the selected port.

$ bkn-specs-editor bundle --destinationPath --format

Receives:

• destinationPath: string

The output file path (defaults to 'spec/index.json').

• format: string (json | yaml)

The output file format (defaults to 'json').

Does: Bundles the multi-file Swagger spec into one.

$ bkn-specs-editor lint

Receives:

Nothing.

Does: Validates the current spec.

License

This project is licensed under the terms of the MIT license