API Specification

Swagger

Swagger Documentation

Tools

Swagger Editor
- Editor
- GitHub
Swagger UI
- Documentation Visualizer
- GitHub
Swagger Codegen
- Code Generator
- GitHub

OpenAPI Specification (OAS)

RESTful APIs (REST APIs)
- REST(REpresentational State Transfer)

Versions

OAS is versioned using Semantic Versioning 2.0.0.

Formats

YAML
- Version 1.2
JSON

Schemas

JSON Schema

OpenAPI document

Minimal openapi.yaml

openapi: 3.0.3
info:
  title: Test
  version: 0.1.0
paths:
  /test:
    get:
      responses:
        default:
          description: Default response.

Parameter Object
- Style Values

Tips

Only parameters, requestBody and responses support multiple examples.

YAML

Nodes

Scalar
Sequence
Mapping

Node Styles

Block Style
Flow Style

# Empty Sequences
[]
# Empty Mappings
{}

Anchors, Aliases

Anchors

Scalar

# Scalar
Scalar: &name
  100

Anchor Scalar Node 100

Sequence

# Sequence
Sequence: &name
  - 100
  - 200
  - 300

Anchor Sequence Node [100, 200, 300]

Mapping

# Mapping
Mapping: &name
  a: 100
  b: 200
  c: 300

Anchor Mapping Node { a: 100, b: 200, c: 300 }

Aliases

Alias: *name

Merge one map

Alias:
  <<: *name
  d: 400

Alias is { a: 100, b: 200, c: 300, d: 400 }

Merge multiple maps

Mapping: &name2
  d: 400
  e: 500
  f: 600

Alias:
  <<: *name
  <<: *name2

Alias is { a: 100, b: 200, c: 300, d: 400, e: 500, f: 600 }

Override

Alias:
  <<: *name
  a: 800

Alias is { a: 800, b: 200, c: 300 }

Redocly

bundle
build-docs
lint

Implementation (nodejs-server)

<nodejs-server>
- index.js
- api
  - openapi.yaml
- controllers
  - Default.js
    - It seems to be separated by tag name.
- service
  - DefaultService.js
    - Implement on this code.
- node_modules
  - oas3-tools