Convert Figma logo to code with AI

swagger-api logoswagger-editor

Swagger Editor

8,865
2,240
8,865
260
View on GitHubView on NPM

Top Related Projects

OpenAPITools's avatar

openapi-generator

21,244

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

stoplightio's avatar

spectral

2,448

A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI v3.1, v3.0, and v2.0 as well as AsyncAPI v2.x.

Redocly's avatar

redoc

23,260

📘 OpenAPI/Swagger-generated API Reference Documentation

apiaryio's avatar

api-blueprint

8,642

API Blueprint

OAI's avatar

OpenAPI-Specification

28,776

The OpenAPI Specification Repository

Quick Overview

Swagger Editor is a browser-based editor for designing, describing, and documenting RESTful APIs using the OpenAPI Specification (formerly known as Swagger). It provides a real-time preview of the API documentation and allows for easy editing of API definitions in YAML or JSON format.

Pros

  • Real-time visualization of API documentation
  • Built-in validation for OpenAPI Specification compliance
  • Supports both YAML and JSON formats
  • Integrates well with other Swagger tools and ecosystem

Cons

  • Limited offline functionality
  • Can be resource-intensive for large API definitions
  • Learning curve for users unfamiliar with OpenAPI Specification
  • Some advanced features may require additional setup or plugins

Getting Started

To use Swagger Editor, you can either:

  1. Visit the online version at https://editor.swagger.io/

  2. Run it locally using Docker:

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

Then open your browser and navigate to http://localhost:80.

  1. Install it as an npm package:
npm install -g swagger-editor-dist
swagger-editor-dist serve

This will start a local server, and you can access the editor at http://localhost:3001.

Once you have the editor open, you can start defining your API by editing the YAML or JSON in the left panel. The right panel will update in real-time to show the rendered API documentation.

Competitor Comparisons

OpenAPITools logo

openapi-generator

21,244

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

Pros of openapi-generator

  • Supports a wide range of programming languages and frameworks for code generation
  • Offers more customization options for generated code
  • Provides a command-line interface for easy integration into build processes

Cons of openapi-generator

  • Steeper learning curve due to its extensive features and options
  • May require more setup and configuration compared to Swagger Editor

Code comparison

Swagger Editor (YAML editing):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users

openapi-generator (CLI usage):

openapi-generator generate -i api.yaml -g java -o ./generated

Key differences

  • Swagger Editor is primarily a browser-based editor for OpenAPI specifications
  • openapi-generator focuses on generating client libraries, server stubs, and documentation
  • Swagger Editor provides real-time validation and visualization of API specifications
  • openapi-generator offers more flexibility in terms of output formats and customization

Use cases

  • Use Swagger Editor for creating and editing OpenAPI specifications visually
  • Choose openapi-generator for generating code across multiple languages and frameworks
  • Combine both tools in a workflow: design with Swagger Editor, then generate code with openapi-generator
stoplightio logo

spectral

2,448

A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI v3.1, v3.0, and v2.0 as well as AsyncAPI v2.x.

Pros of Spectral

  • More flexible and customizable linting rules
  • Can be used as a standalone CLI tool or integrated into CI/CD pipelines
  • Supports multiple API description formats (OpenAPI, AsyncAPI, JSON Schema)

Cons of Spectral

  • Lacks built-in editing capabilities
  • Requires more setup and configuration for advanced use cases
  • May have a steeper learning curve for beginners

Code Comparison

Spectral (custom rule):

module.exports = {
  rules: {
    'operation-description': {
      given: '$.paths.*[get,post,put,delete]',
      then: {
        field: 'description',
        function: 'truthy'
      }
    }
  }
};

Swagger Editor (built-in validation):

paths:
  /users:
    get:
      summary: Get users
      description: Retrieve a list of users
      responses:
        '200':
          description: Successful response

Spectral focuses on customizable linting and validation, while Swagger Editor provides a more integrated editing and preview experience for OpenAPI specifications. Spectral offers greater flexibility in rule creation and supports multiple API formats, making it suitable for complex validation scenarios. However, Swagger Editor excels in providing a user-friendly interface for editing and visualizing OpenAPI documents, which may be more accessible for users who prefer a GUI-based approach.

Redocly logo

redoc

23,260

📘 OpenAPI/Swagger-generated API Reference Documentation

Pros of Redoc

  • Offers a more modern and visually appealing documentation interface
  • Provides better support for complex API structures and nested objects
  • Allows for easier customization of the documentation layout and styling

Cons of Redoc

  • Lacks built-in editing capabilities, focusing primarily on rendering
  • May require additional setup and configuration compared to Swagger Editor
  • Has a steeper learning curve for advanced customization

Code Comparison

Swagger Editor (YAML):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get users

Redoc (HTML):

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
  </head>
  <body>
    <redoc spec-url="path/to/openapi.yaml"></redoc>
  </body>
</html>

Swagger Editor is an all-in-one solution for editing and previewing OpenAPI specifications, while Redoc focuses on rendering beautiful and interactive API documentation. Swagger Editor provides a more integrated experience for API design and documentation, whereas Redoc excels in creating polished, user-friendly documentation for consumers of the API.

apiaryio logo

api-blueprint

8,642

API Blueprint

Pros of API Blueprint

  • Simpler, more human-readable syntax using Markdown
  • Better support for documentation-first API design
  • Easier to learn for non-technical stakeholders

Cons of API Blueprint

  • Less widespread adoption compared to Swagger/OpenAPI
  • Fewer tools and integrations available in the ecosystem
  • Limited support for complex API structures and advanced features

Code Comparison

API Blueprint:

# GET /users/{id}
+ Parameters
    + id: 1 (number, required) - User ID
+ Response 200 (application/json)
    + Attributes
        + name: John Doe (string)
        + email: john@example.com (string)

Swagger Editor (YAML):

/users/{id}:
  get:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string

Both Swagger Editor and API Blueprint are popular tools for API design and documentation. Swagger Editor, part of the OpenAPI ecosystem, offers a more comprehensive set of features and wider industry adoption. API Blueprint, on the other hand, provides a simpler, more readable syntax that can be easier for non-technical team members to understand and contribute to. The choice between the two often depends on the specific needs of the project and the team's preferences.

OAI logo

OpenAPI-Specification

28,776

The OpenAPI Specification Repository

Pros of OpenAPI-Specification

  • Serves as the official standard for API description
  • Provides a comprehensive, language-agnostic specification
  • Widely adopted and supported by various tools and platforms

Cons of OpenAPI-Specification

  • Lacks built-in editing capabilities
  • Requires additional tools for visualization and testing
  • May have a steeper learning curve for beginners

Code Comparison

OpenAPI-Specification (YAML):

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Swagger-Editor (JavaScript):

SwaggerEditor.create(element, {
  swagger: '2.0',
  info: {
    title: 'Sample API',
    version: '1.0.0'
  }
});

Key Differences

  • OpenAPI-Specification focuses on defining the API structure
  • Swagger-Editor provides an interactive editing environment
  • OpenAPI-Specification is more flexible and extensible
  • Swagger-Editor offers real-time validation and documentation

Use Cases

  • OpenAPI-Specification: Standardizing API definitions across teams
  • Swagger-Editor: Rapid prototyping and visual API design

Community and Support

  • OpenAPI-Specification: Large community, extensive third-party tooling
  • Swagger-Editor: Well-maintained, part of the Swagger ecosystem

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

NPM version Build Status Code Climate Build Status

⏰️ Looking for the next generation version of Swagger Editor?

SwaggerEditor is now released under two major release channels:

  1. SwaggerEditor@4 - released from master branch and deployed at https://editor.swagger.io/
  2. SwaggerEditor@5 - released from next branch and deployed at https://editor-next.swagger.io/

Only SwaggerEditor@5 supports OpenAPI 3.1.0. SwaggerEditor@4 will not receive OpenAPI 3.1.0 support and is considered legacy at this point. The plan is to continually migrate fully to SwaggerEditor@5 and deprecate the SwaggerEditor@4 in the future.

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

Swagger Editor lets you edit OpenAPI API definitions (OpenAPI 2.0 and OpenAPI 3.0.3) in JSON or YAML format inside your browser and to preview documentations in real time. Valid OpenAPI definitions 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.

Helpful scripts

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

Developing

Script nameDescription
devSpawn a hot-reloading dev server on port 3200.
deps-checkGenerate a size and licensing report on Swagger Editors's dependencies.
lintReport ESLint style errors and warnings.
lint-errorsReport ESLint style errors, without warnings.
lint-fixAttempt to fix style errors automatically.
watchRebuild the core files in /dist when the source code changes. Useful for npm link.

Building

Script nameDescription
buildBuild a new set of JS and CSS assets, and output them to /dist.
build:bundleBuild swagger-editor-bundle.js only (commonJS).
build:coreBuild swagger-editor.(js|css) only (commonJS).
build:standaloneBuild swagger-editor-standalone-preset.js only (commonJS).
build:stylesheetsBuild swagger-editor.css only.
build:es:bundleBuild swagger-editor-es-bundle.js only (es2015).
build:es:bundle:coreBuild swagger-editor-es-bundle-core.js only (es2015).

Testing

Script nameDescription
testRun unit tests in Node, run Cypress end-to-end tests, and run ESLint in errors-only mode.
test:unit-mochaRun Mocha-based unit tests in Node.
test:unit-jestRun Jest-based unit tests in Node.
e2eRun end-to-end browser tests with Cypress.
lintRun ESLint test
test:artifactRun list of bundle artifact tests in Jest
test:artifact:umd:bundleRun unit test that confirms swagger-editor-bundle exports as a Function
test:artifact:es:bundleRun unit test that confirms swagger-editor-es-bundle exports as a Function
test:artifact:es:bundle:coreRun unit test that confirms swagger-editor-es-bundle-core exports as a Function

Running locally

Prerequisites

  • git, any version
  • Node.js >=20.3.0 and npm >=9.6.7 are the minimum required versions that this repo runs on, but we always recommend using the latest version of Node.js.
 $ npm i --legacy-peer-deps

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 a URL pointing to an API definition (may not be available if some security policies such as CSP or CORS are enforced):
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
  • You can provide your own json or yaml definition file from your local host:
docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

Note: When both URL and SWAGGER_FILE environment variables are set, URL has priority and SWAGGER_FILE is ignored.

  • You can specify a different base url via BASE_URL variable 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
  • You can specify a different port via PORT variable for accessing the application, default is 8080.
docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
  • You can specify Google Tag Manager ID via GTM variable for tracking the usage of the swagger-editor.
docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor

You can also customize the different endpoints used by the Swagger Editor with the following environment variables. For instance, this can be useful if you have your own Swagger generator server:

Environment variableDefault value
URL_SWAGGER2_GENERATORhttps://generator.swagger.io/api/swagger.json
URL_OAS3_GENERATORhttps://generator3.swagger.io/openapi.json
URL_SWAGGER2_CONVERTERhttps://converter.swagger.io/api/convert

If you want to run the Swagger Editor locally without the Codegen features (Generate Server and Generate Client) you can set the above environment variables to null (URL_SWAGGER2_CONVERTER=null).

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

Using older version of React

[!IMPORTANT] By older versions we specifically refer to React >=17 <18.

By default swagger-editor@4 npm package comes with latest version of React@18. It's possible to use swagger-editor@4 npm package with older version of React.

Let's say my application integrates with swagger-editor@4 npm package and uses React@17.0.2.

npm

In order to inform swagger-editor@4 npm package that I require it to use my React version, I need to use npm overrides.

{
  "dependencies": {
    "react": "=17.0.2",
    "react-dom": "=17.0.2"
  },
  "overrides": {
    "swagger-editor": {
      "react": "$react",
      "react": "$react-dom",
      "react-redux": "^8"
    }
  }
}

[!NOTE] The React and ReactDOM override are defined as a reference to the dependency. Since react-redux@9 only supports React >= 18, we need to use react-redux@8.

yarn

In order to inform swagger-editor@4 npm package that I require it to use my specific React version, I need to use yarn resolutions.

{
  "dependencies": {
    "react": "17.0.2",
    "react-dom": "17.0.2"
  },
  "resolutions": {
    "swagger-editor/react": "17.0.2",
    "swagger-editor/react-dom": "17.0.2",
    "swagger-editor/react-redux": "^8"
  }
}

[!NOTE] The React and ReactDOM resolution cannot be defined as a reference to the dependency. Unfortunately yarn does not support aliasing like $react or $react-dom as npm does. You'll need to specify the exact versions.

Security contact

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

NPM DownloadsLast 30 Days