Shard Detail

swagger v0.3.0

Swagger contains a OpenAPI / Swagger universal documentation generator and HTTP server handler.
crystal crystal-http-handler crystal-api-document swagger swagger-generator swagger-documentation

Install & Use

Add the following code to your project's shard.yml under:

dependencies to use in production
- OR -
development_dependencies to use in development

  github: icyleaf/swagger



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


Swagger is a open source, collaboratively funded project. If you run a business and are using Swagger in a revenue-generating product, it would make business sense to sponsor Swagger development. Individual users are also welcome to make a one time donation if Swagger has helped you in your work or personal projects.

You can donate via Paypal.

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