LIGHT

  • News
  • Docs
  • Community
  • Reddit
  • GitHub

Swagger Editor

Swagger Editor for OpenAPI Specification

Introduction

Swagger is a simple yet powerful representation of your RESTful API. With the largest ecosystem of API tooling on the planet, thousands of developers are supporting Swagger in almost every modern programming language and deployment environment. With a Swagger-enabled API, you get interactive documentation, client SDK generation and discoverability.

Swagger was created to help fulfill the promise of APIs and is 100% open source software.

The Swagger specification defines a set of files required to describe an API. These files can then be used by the Swagger-UI project to display the API and Swagger-codegen to generate clients or servers in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

Swagger Editor

Specification Management

If you only have one API to be built, you can save your specification anywhere and you don’t need any external references; however, you might work for an organization which is building hundreds or thousands APIs and there are so many shared references between APIs like common headers, error status etc. In this case, it is recommended to create a separate repo for specification only. Normally, it will be called swagger.

Within this folder, each api will have its own sub folder and common shared references will be in the root folder.

Swagger spec. can be edited in yaml or json format but most people will be using yaml format and we are stick to it.

Using the online editor

To access the Swagger online editor, click the following link.

Online Swagger Editor

  • To create a new specification - File –> New

  • To import an existing specification from the File –> Import File …

  • To save/export the specification in YAML format - File –> Download YAML.

Online editors work if you are working on only one API without any externalized references. If you want to work with multiple APIs, you have to run the editor locally.

Running editor locally

git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start

Now your default browser will be started and point to 127.0.0.1:8080/# with a sample specification loaded.

Create a new specification

The swagger-editor serves the static files via an HTTP server. To work on API specifications, the simplest way is to clone the swagger repository directly in the Swagger editor folder.

cd swagger-editor
git clone https://github.com/networknt/swagger.git
cd swagger

When saving/exporting your specification, please use swagger.yaml filename in your API sub folder under swagger. Common object specifications are located in the root folder of the /swagger repository. Ex. header.yaml, error.yaml, etc. To refer these common specification files in API specification

$ref: 'swagger/error.yaml#/error'

model-config

In the Github networknt organization, we have a repo model-config that contains specifications and light-codegen configurations with README.md to generate projects. You can find OpenAPI specifications in the rest folder.

Usually, we are using the online swagger editor to create/update OpenAPI 3.0 specifications and then export to both YAML and JSON format to save them into the model-config repo.

Useful links

OpenAPI Specification Official Examples Tutorial

  • About Light
    • Overview
    • Testimonials
    • What is Light
    • Features
    • Principles
    • Benefits
    • Roadmap
    • Community
    • Articles
    • Videos
    • License
    • Why Light Platform
  • Getting Started
    • Get Started Overview
    • Environment
    • Light Codegen Tool
    • Light Rest 4j
    • Light Tram 4j
    • Light Graphql 4j
    • Light Hybrid 4j
    • Light Eventuate 4j
    • Light Oauth2
    • Light Portal Service
    • Light Proxy Server
    • Light Router Server
    • Light Config Server
    • Light Saga 4j
    • Light Session 4j
    • Webserver
    • Websocket
    • Spring Boot Servlet
  • Architecture
    • Architecture Overview
    • API Category
    • API Gateway
    • Architecture Patterns
    • CQRS
    • Eco System
    • Event Sourcing
    • Fail Fast vs Fail Slow
    • Integration Patterns
    • JavaEE declining
    • Key Distribution
    • Microservices Architecture
    • Microservices Monitoring
    • Microservices Security
    • Microservices Traceability
    • Modular Monolith
    • Platform Ecosystem
    • Plugin Architecture
    • Scalability and Performance
    • Serverless
    • Service Collaboration
    • Service Mesh
    • SOA
    • Spring is bloated
    • Stages of API Adoption
    • Transaction Management
    • Microservices Cross-cutting Concerns Options
    • Service Mesh Plus
    • Service Discovery
  • Design
    • Design Overview
    • Design First vs Code First
    • Desgin Pattern
    • Service Evolution
    • Consumer Contract and Consumer Driven Contract
    • Handling Partial Failure
    • Idempotency
    • Server Life Cycle
    • Environment Segregation
    • Database
    • Decomposition Patterns
    • Http2
    • Test Driven
    • Multi-Tenancy
    • Why check token expiration
    • WebServices to Microservices
  • Cross-Cutting Concerns
    • Concerns Overview
  • API Styles
    • Light-4j for absolute performance
    • Style Overview
    • Distributed session on IMDG
    • Hybrid Serverless Modularized Monolithic
    • Kafka - Event Sourcing and CQRS
    • REST - Representational state transfer
    • Web Server with Light
    • Websocket with Light
    • Spring Boot Integration
    • Single Page Application
    • GraphQL - A query language for your API
    • Light IBM MQ
    • Light AWS Lambda
    • Chaos Monkey
  • Infrastructure Services
    • Service Overview
    • Light Proxy
    • Light Mesh
    • Light Router
    • Light Portal
    • Messaging Infrastructure
    • Centralized Logging
    • COVID-19
    • Light OAuth2
    • Metrics and Alerts
    • Config Server
    • Tokenization
    • Light Controller
  • Tool Chain
    • Tool Chain Overview
  • Utility Library
  • Service Consumer
    • Service Consumer
  • Development
    • Development Overview
  • Deployment
    • Deployment Overview
    • Frontend Backend
    • Linux Service
    • Windows Service
    • Install Eventuate on Windows
    • Secure API
    • Client vs light-router
    • Memory Limit
    • Deploy to Kubernetes
  • Benchmark
    • Benchmark Overview
  • Tutorial
    • Tutorial Overview
  • Troubleshooting
    • Troubleshoot
  • FAQ
    • FAQ Overview
  • Milestones
  • Contribute
    • Contribute to Light
    • Development
    • Documentation
    • Example
    • Tutorial
“Swagger Editor” was last updated: July 30, 2021: fixes #280 add http-sidecar k8s config and update index (e20e033)
Improve this page
  • News
  • Docs
  • Community
  • Reddit
  • GitHub
  • About Light
  • Getting Started
  • Architecture
  • Design
  • Cross-Cutting Concerns
  • API Styles
  • Infrastructure Services
  • Tool Chain
  • Utility Library
  • Service Consumer
  • Development
  • Deployment
  • Benchmark
  • Tutorial
  • Troubleshooting
  • FAQ
  • Milestones
  • Contribute