Nobody Prefers Margarine

    @beakyn/specs-editor

    1.4.2 • Public • Published

    Beakyn Specs Editor

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

    Table of Contents

    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

    Install

    npm i @beakyn/specs-editor

    DownloadsWeekly Downloads

    1

    Version

    1.4.2

    License

    MIT

    Unpacked Size

    162 kB

    Total Files

    12

    Last publish

    Collaborators

    • nelsoneldoro
    • jpbeakyn
    • juanpujol
    • abraaoalves
    • falcaoaugustos
    • brunolazarus
    • hileomsi
    • murilopaixao