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.
dependencies:
swagger:
github: icyleaf/swagger
require "swagger"
builder = Swagger::Builder.new(
title: "App API",
version: "1.0.0",
description: "This is a sample api for users",
terms_url: "http://yourapp.com/terms",
contact: Swagger::Contact.new("icyleaf", "icyleaf.cn@gmail.com", "http://icyleaf.com"),
license: Swagger::License.new("MIT", "https://github.com/icyleaf/swagger/blob/master/LICENSE"),
authorizations: [
Swagger::Authorization.jwt(description: "Use JWT Auth"),
]
)
builder.add(Swagger::Controller.new("Users", "User resources", [
Swagger::Action.new("get", "/users", description: "All users", responses: [
Swagger::Response.new("200", "Success response")
]),
Swagger::Action.new("get", "/users/{id}", description: "Get user by id", parameters: [
Swagger::Parameter.new("id", "path")
], responses: [
Swagger::Response.new("200", "Success response"),
Swagger::Response.new("404", "Not found user")
], authorization: true),
Swagger::Action.new("post", "/users", description: "Create User", responses: [
Swagger::Response.new("201", "Return user resource after created"),
Swagger::Response.new("401", "Unauthorizated")
], authorization: false)
]))
document = builder.built
puts document.to_json
Structure in src
directory:
.
├── xxx.cr # Friendly APIs
├── http # HTTP assets and libraries
└── objects # OpenAPI objects
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::HTTP::Server.run(document)
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
- PathItem Object
- Tags Object
- Servers Objec
- ServerVariables Object
- Security Object
- Components Object
- Schemas Object
- SecuritySchemes Object
- Basic
- Bearer (include JWT)
- APIKey
- OAuth2
- ExternalDocs Object
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.
- 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