Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Language Tag Source Document Build Status

Swagger is a low-level library which generates a document compatible with Swagger / OpenAPI Spec 3.0.3, and wrapped many friendly APIs let developer understand and use it easier.


    github: icyleaf/swagger

Quick look

require "swagger"

builder =
  title: "App API",
  version: "1.0.0",
  description: "This is a sample api for users",
  terms_url: "",
  contact:"icyleaf", "", ""),
  license:"MIT", ""),
  authorizations: [
    Swagger::Authorization.jwt(description: "Use JWT Auth"),

builder.add("Users", "User resources", ["get", "/users", description: "All users", responses: ["200", "Success response")
  ]),"get", "/users/{id}", description: "Get user by id", parameters: ["id", "path")
  ], responses: ["200", "Success response"),"404", "Not found user")
  ], authorization: true),"post", "/users", description: "Create User", responses: ["201", "Return user resource after created"),"401", "Unauthorizated")
  ], authorization: false)

document = builder.built
puts document.to_json


Structure in src directory:

├──                        # Friendly APIs
├── http                          # HTTP assets and libraries
└── objects                       # OpenAPI objects

Running on web

Swagger provids a built-in web server, if you have no idea how to preview it:

require "swagger"
require "swagger/http/server"

# made your document (See `builder` code example above)
document = builder.built

# Run web server


Swagger has two HTTP handlers which you can integrate it to bult-in HTTP Server and mostly frameworks (like kemal, amber, lucky etc):

  • Swagger::HTTP::APIHandler
  • Swagger::HTTP::WebHandler


See more examples.


  • openapi
  • Info Object
  • Paths Object
    • PathItem Object
      • Parameter Object
      • RequestBody Object
      • Responses Object
      • Security Object
      • Tag Object
  • Tags Object
  • Servers Objec
    • ServerVariables Object
  • Security Object
  • Components Object
    • Schemas Object
    • SecuritySchemes Object
      • Basic
      • Bearer (include JWT)
      • APIKey
      • OAuth2
  • ExternalDocs Object

How to Contribute

Your contributions are always welcome! Please submit a pull request or create an issue to add a new question, bug or feature to the list.

Here is a throughput graph of the repository for the last few weeks:

All Contributors are on the wall.

You may also like

  • halite - HTTP Requests Client with a chainable REST API, built-in sessions and middlewares.
  • totem - Load and parse a configuration file or string in JSON, YAML, dotenv formats.
  • markd - Yet another markdown parser built for speed, Compliant to CommonMark specification.
  • poncho - A .env parser/loader improved for performance.
  • popcorn - Easy and Safe casting from one type to another.
  • fast-crystal - 💨 Writing Fast Crystal 😍 -- Collect Common Crystal idioms.


MIT License © icyleaf