Convert Figma logo to code with AI

swagger-api logoswagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

26,457
8,954
26,457
1,208
View on GitHubView on NPM

Top Related Projects

Redocly's avatar

redoc

23,261

📘 OpenAPI/Swagger-generated API Reference Documentation

OpenAPITools's avatar

openapi-generator

21,595

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

apiaryio's avatar

api-blueprint

8,648

API Blueprint

Mermade's avatar

openapi-gui

1,404

GUI / visual editor for creating and editing OpenAPI / Swagger definitions

Mermade's avatar

widdershins

1,479

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

Quick Overview

Swagger UI is an open-source tool that generates a user-friendly interface for exploring and testing RESTful APIs. It dynamically renders interactive API documentation from OpenAPI (formerly Swagger) specifications, allowing developers to visualize and interact with API resources without needing to implement the API themselves.

Pros

  • Easy integration with existing API projects
  • Automatically generates interactive documentation from OpenAPI specifications
  • Supports multiple authentication methods
  • Customizable appearance to match branding requirements

Cons

  • Can be resource-intensive for large API specifications
  • Limited customization options for complex use cases
  • Occasional rendering issues with certain browser versions
  • May require additional configuration for advanced security setups

Code Examples

  1. Basic HTML integration:
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>SwaggerUI</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
</head>
<body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
    <script>
        window.onload = () => {
            window.ui = SwaggerUIBundle({
                url: 'https://petstore.swagger.io/v2/swagger.json',
                dom_id: '#swagger-ui',
            });
        };
    </script>
</body>
</html>
  1. Customizing the UI theme:
SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    theme: {
        colors: {
            primary: {
                main: '#1E90FF'
            }
        }
    }
});
  1. Using a pre-specified API definition:
SwaggerUIBundle({
    spec: {
        openapi: "3.0.0",
        info: {
            title: "Sample API",
            version: "1.0.0"
        },
        paths: {
            "/hello": {
                get: {
                    summary: "Returns a greeting",
                    responses: {
                        "200": {
                            description: "Successful response",
                            content: {
                                "application/json": {
                                    schema: {
                                        type: "object",
                                        properties: {
                                            message: {
                                                type: "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    dom_id: '#swagger-ui'
});

Getting Started

To integrate Swagger UI into your project:

  1. Include the Swagger UI CSS and JavaScript files in your HTML:
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
  1. Create a container element for the UI:
<div id="swagger-ui"></div>
  1. Initialize Swagger UI with your API specification:
window.onload = () => {
    window.ui = SwaggerUIBundle({
        url: 'path/to/your/api-spec.json',
        dom_id: '#swagger-ui',
    });
};

Replace 'path/to/your/api-spec.json' with the URL or path to your OpenAPI specification file.

Competitor Comparisons

Redocly logo

redoc

23,261

📘 OpenAPI/Swagger-generated API Reference Documentation

Pros of Redoc

  • Cleaner, more modern UI design with better readability
  • Built-in search functionality for API documentation
  • Supports themes and customization options

Cons of Redoc

  • Less widespread adoption compared to Swagger UI
  • Fewer built-in interactive features for API testing

Code Comparison

Redoc:

<!DOCTYPE html>
<html>
  <head>
    <title>API Documentation</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
  </head>
  <body>
    <redoc spec-url="https://petstore.swagger.io/v2/swagger.json"></redoc>
  </body>
</html>

Swagger UI:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>SwaggerUI</title>
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
    <script>
      window.onload = () => {
        window.ui = SwaggerUIBundle({
          url: "https://petstore.swagger.io/v2/swagger.json",
          dom_id: '#swagger-ui',
        });
      };
    </script>
  </body>
</html>

Both Redoc and Swagger UI are popular tools for rendering OpenAPI (Swagger) specifications. Redoc offers a more modern and clean interface, while Swagger UI provides more interactive features for API testing. The choice between the two depends on specific project requirements and personal preferences.

OpenAPITools logo

openapi-generator

21,595

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

  • Generates client libraries, server stubs, and documentation for multiple languages and frameworks
  • Supports a wider range of OpenAPI/Swagger versions (2.0, 3.0, 3.1)
  • Offers more customization options for generated code

Cons of openapi-generator

  • Steeper learning curve due to its extensive features and options
  • Requires more setup and configuration compared to swagger-ui
  • May generate unnecessary code for simpler API projects

Code comparison

swagger-ui (HTML):

<div id="swagger-ui"></div>
<script src="swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui'
  })
</script>

openapi-generator (CLI):

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

Summary

swagger-ui is primarily focused on rendering interactive API documentation in the browser, while openapi-generator is a powerful tool for generating various API-related artifacts across multiple languages and frameworks. swagger-ui is easier to set up and use for simple API documentation needs, whereas openapi-generator offers more flexibility and extensive code generation capabilities at the cost of increased complexity.

apiaryio logo

api-blueprint

8,648

API Blueprint

Pros of API Blueprint

  • More human-readable and easier to write, using Markdown syntax
  • Supports more detailed documentation, including extended descriptions and examples
  • Better suited for design-first API development approaches

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)
    + Body
        {
            "id": 1,
            "name": "John Doe"
        }

Swagger UI (OpenAPI):

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

Summary

API Blueprint offers a more human-friendly approach to API documentation, making it easier for non-technical stakeholders to understand and contribute. However, Swagger UI, based on the OpenAPI Specification, provides a more comprehensive ecosystem and wider industry adoption. The choice between the two depends on specific project requirements, team preferences, and the desired balance between simplicity and feature richness.

Mermade logo

openapi-gui

1,404

GUI / visual editor for creating and editing OpenAPI / Swagger definitions

Pros of openapi-gui

  • Lightweight and focused specifically on OpenAPI editing
  • Provides a more streamlined interface for quick edits
  • Offers a simpler learning curve for beginners

Cons of openapi-gui

  • Less feature-rich compared to swagger-ui
  • Smaller community and fewer updates
  • Limited customization options

Code Comparison

swagger-ui:

import SwaggerUI from 'swagger-ui'
import 'swagger-ui/dist/swagger-ui.css'

SwaggerUI({
  dom_id: '#swagger-ui',
  url: 'https://petstore.swagger.io/v2/swagger.json'
})

openapi-gui:

import OpenAPIEditor from 'openapi-gui'

const editor = new OpenAPIEditor({
  element: document.getElementById('editor'),
  spec: yourOpenAPISpec
})

Both repositories aim to provide tools for working with OpenAPI specifications, but they serve different purposes. swagger-ui is primarily focused on rendering and interacting with API documentation, while openapi-gui is designed for editing OpenAPI specifications.

swagger-ui offers a more comprehensive set of features and has a larger community, making it ideal for projects that require extensive API documentation and interaction. It's widely adopted and well-maintained, with regular updates and improvements.

openapi-gui, on the other hand, provides a more focused editing experience for OpenAPI specifications. It's lighter and potentially easier to integrate into existing projects for quick edits. However, it may lack some of the advanced features and customization options available in swagger-ui.

The choice between the two depends on the specific needs of your project, whether you prioritize documentation rendering or specification editing.

Mermade logo

widdershins

1,479

OpenAPI / Swagger, AsyncAPI & Semoasa definitions to (re)Slate compatible markdown

Pros of Widdershins

  • Generates documentation in multiple formats (Markdown, HTML, Slate)
  • Supports a wider range of API specification formats (OpenAPI, AsyncAPI, Semoasa)
  • Offers more customization options for output

Cons of Widdershins

  • Requires command-line usage or integration into build processes
  • Less user-friendly for non-technical users
  • Lacks interactive features found in Swagger UI

Code Comparison

Swagger UI (HTML):

<div id="swagger-ui"></div>
<script src="swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui'
  })
</script>

Widdershins (Command-line):

widdershins --search false --language_tabs 'javascript:JavaScript' 'python:Python' --summary openapi.yaml -o output.md

Summary

Swagger UI is a popular, interactive web-based solution for rendering OpenAPI specifications, while Widdershins is a versatile documentation generator supporting multiple input and output formats. Swagger UI excels in providing an easy-to-use, interactive interface for exploring APIs, making it ideal for end-users and developers. Widdershins, on the other hand, offers more flexibility in output formats and customization options, making it suitable for generating static documentation or integrating into existing documentation workflows.

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 npm audit total GitHub contributors

monthly npm installs total docker pulls monthly packagist installs gzip size

Introduction

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

General

👉🏼 Want to score an easy open-source contribution? Check out our Good first issue label.

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

This repository publishes three different NPM modules:

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

We strongly suggest that you use swagger-ui instead of swagger-ui-dist if you're building a single-page application, since swagger-ui-dist is significantly larger.

If you are looking for plain ol' HTML/JS/CSS, download the latest release and copy the contents of the /dist folder to your server.

Compatibility

The OpenAPI Specification has undergone 5 revisions since initial creation in 2010. Compatibility between Swagger UI and the OpenAPI Specification is as follows:

Swagger UI VersionRelease DateOpenAPI Spec compatibilityNotes
5.0.02023-06-122.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0tag v5.0.0
4.0.02021-11-032.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3tag v4.0.0
3.18.32018-08-032.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3tag v3.18.3
3.0.212017-07-262.0tag v3.0.21
2.2.102017-01-041.1, 1.2, 2.0tag v2.2.10
2.1.52016-07-201.1, 1.2, 2.0tag v2.1.5
2.0.242014-09-121.1, 1.2tag v2.0.24
1.0.132013-03-081.1, 1.2tag v1.0.13
1.0.12011-10-111.0, 1.1tag v1.0.1

Documentation

Usage

Customization

Development

Contributing

Integration Tests

You will need JDK of version 7 or higher as instructed here https://nightwatchjs.org/guide/getting-started/installation.html#install-selenium-server

Integration tests can be run locally with npm run e2e - be sure you aren't running a dev server when testing!

Browser support

Swagger UI 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.

  • Only part of the parameters previously supported are available.
  • The JSON Form Editor is not implemented.
  • Support for collectionFormat is partial.
  • l10n (translations) is not implemented.
  • Relative path support for external files is not implemented.

Security contact

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

License

SwaggerUI is licensed under Apache 2.0 license. SwaggerUI comes with an explicit NOTICE file containing additional legal notices and information.

NPM DownloadsLast 30 Days