swagger
Swagger
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.
Installation
dependencies:
swagger:
github: icyleaf/swagger
Quick look
require "swagger"
builder = Swagger::Builder.new(
title: "App API",
version: "1.0.0",
description: "This is a sample api for users",
terms: "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", "All users"),
Swagger::Action.new("get", "/users/{id}", "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", "Create User", responses: [
Swagger::Response.new("201", "Return user resource after created"),
Swagger::Response.new("401", "Unauthorizated")
], authorization: false)
]))
document = builder.built
p document
Structure
Structure in src
directory:
.
├── xxx.cr # 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
document = builder.built
# Run web server
Swagger::HTTP::Server.run(builder.built)
Integrating
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
Examples
See more examples.
Todo
- [x] openapi
- [x] Info Object
- [x] Paths Object
- [x] PathItem Object
- [x] Parameter Object
- [x] RequestBody Object
- [x] Responses Object
- [x] Security Object
- [x] Tag Object
- [x] PathItem Object
- [x] Tags Object
- [x] Servers Objec
- [x] ServerVariables Object
- [x] Security Object
- [x] Components Object
- [x] Schemas Object
- [x] SecuritySchemes Object
- [x] Basic
- [x] Bearer (include JWT)
- [x] APIKey
- [x] OAuth2
- [x] ExternalDocs Object
Donate
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.
License
MIT License © icyleaf