swagger-editor

    3.18.2 • Public • Published

    NPM version Build Status Code Climate Dependency Status devDependency Status Build Status

    🕰️ Looking for the older version of Swagger Editor? Refer to the 2.x branch.

    Swagger Editor lets you edit Swagger API specifications in YAML inside your browser and to preview documentations in real time. Valid Swagger JSON descriptions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).

    As a brand new version, written from the ground up, there are some known issues and unimplemented features. Check out the Known Issues section for more details.

    This repository publishes to two different NPM modules:

    • swagger-editor is a traditional npm module intended for use in single-page applications that are capable of resolving dependencies (via Webpack, Browserify, etc).
    • swagger-editor-dist is a dependency-free module that includes everything you need to serve Swagger Editor in a server-side project, or a web project that can't resolve npm module dependencies.

    If you're building a single-page application, using swagger-editor is strongly recommended, since swagger-editor-dist is significantly larger.

    For the older version of swagger-editor, refer to the 2.x branch.

    Helpful scripts

    Any of the scripts below can be run by typing npm run <script name> in the project's root directory.

    Developing

    Script name Description
    dev Spawn a hot-reloading dev server on port 3200.
    deps-check Generate a size and licensing report on Swagger Editors's dependencies.
    lint Report ESLint style errors and warnings.
    lint-errors Report ESLint style errors, without warnings.
    lint-fix Attempt to fix style errors automatically.
    watch Rebuild the core files in /dist when the source code changes. Useful for npm link.

    Building

    Script name Description
    build Build a new set of JS and CSS assets, and output them to /dist.
    build:bundle Build swagger-editor-bundle.js only (commonJS).
    build:core Build swagger-editor.(js|css) only (commonJS).
    build:standalone Build swagger-editor-standalone-preset.js only (commonJS).
    build:stylesheets Build swagger-editor.css only.
    build:es:bundle Build swagger-editor-es-bundle.js only (es2015).
    build:es:bundle:core Build swagger-editor-es-bundle-core.js only (es2015).

    Testing

    Script name Description
    test Run unit tests in Node, run Cypress end-to-end tests, and run ESLint in errors-only mode.
    test:unit-mocha Run Mocha-based unit tests in Node.
    test:unit-jest Run Jest-based unit tests in Node.
    e2e Run end-to-end browser tests with Cypress.
    lint Run ESLint test
    test:artifact Run list of bundle artifact tests in Jest
    test:artifact:umd:bundle Run unit test that confirms swagger-editor-bundle exports as a Function
    test:artifact:es:bundle Run unit test that confirms swagger-editor-es-bundle exports as a Function
    test:artifact:es:bundle:core Run unit test that confirms swagger-editor-es-bundle-core exports as a Function

    Running locally

    Prerequisites
    • NPM >=6.12.x

    Generally, we recommend the following guidelines from Node.js Releases to only use Active LTS or Maintenance LTS releases.

    Current Node.js:

    • Node.js 16.x
    • NPM >=7.10.x

    Current Node.js Active LTS:

    • Node.js 14.x
    • NPM >=6.12.x

    Current Node.js Maintenance LTS:

    • Node.js >=12.4
    • NPM >=6.12.x

    If you have Node.js and npm installed, you can run npm start to spin up a static server.

    Otherwise, you can open index.html directly from your filesystem in your browser.

    If you'd like to make code changes to Swagger Editor, you can start up a Webpack hot-reloading dev server via npm run dev.

    Browser support

    Swagger Editor works in the latest versions of Chrome, Safari, Firefox, and Edge.

    Known Issues

    To help with the migration, here are the currently known issues with 3.X. This list will update regularly, and will not include features that were not implemented in previous versions.

    Docker

    Running the image from DockerHub

    There is a docker image published in DockerHub.

    To use this, run the following:

    docker pull swaggerapi/swagger-editor
    docker run -d -p 80:8080 swaggerapi/swagger-editor
    

    This will run Swagger Editor (in detached mode) on port 80 on your machine, so you can open it by navigating to http://localhost in your browser.

    • You can provide your own json or yaml definition file on your host
    docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
    
    • You can provide a API document from your local machine — for example, if you have a file at ./bar/swagger.json:
    docker run -d -p 80:8080 -e URL=/foo/swagger.json -v /bar:/usr/share/nginx/html/foo swaggerapi/swagger-editor
    
    • You can specify a different base url for accessing the application - for example if you want the application to be available at http://localhost/swagger-editor/:
    docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
    

    Building and running an image locally

    To build and run a docker image with the code checked out on your machine, run the following from the root directory of the project:

    # Install npm packages (if needed)
    npm install
    
    # Build the app
    npm run build
    
    # Build an image
    docker build -t swagger-editor .
    
    # Run the container
    docker run -d -p 80:8080 swagger-editor
    
    

    You can then view the app by navigating to http://localhost in your browser.

    Documentation

    Security contact

    Please disclose any security-related issues or vulnerabilities by emailing security@swagger.io, instead of using the public issue tracker.

    Keywords

    none

    Install

    npm i swagger-editor

    DownloadsWeekly Downloads

    8,255

    Version

    3.18.2

    License

    Apache-2.0

    Unpacked Size

    25.1 MB

    Total Files

    13

    Last publish

    Collaborators

    • swagger-api
    • swagger
    • mohsen
    • kyleshockey