Swagger

Swagger is low-level library which generate output compatible with Swagger / OpenAPI Spec 3.0.1, and wrapped many friendly API 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", "[email protected]", "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")
  ]),
  Swagger::Action.new("post", "/users", "Create User", responses: [
    Swagger::Response.new("201", "Return user resource after created"),
    Swagger::Response.new("401", "Unauthorizated")
  ])
]))

document = builder.built
p document

Structure

.
├── action.cr
├── authorization.cr
├── builder.cr
├── controller.cr
├── error.cr
├── object.cr
├── parameter.cr
├── property.cr
├── request.cr
├── response.cr
├── server.cr
├── http                          # HTTP libraries
│   ├── assets
│   ├── handers
│   ├── handler.cr
│   ├── server.cr
│   └── views
└── objects                       # OpenAPI objects
    ├── components.cr
    ├── document.cr
    ├── encoding.cr
    ├── example.cr
    ├── external_docs.cr
    ├── header.cr
    ├── info.cr
    ├── link.cr
    ├── media_type.cr
    ├── operation.cr
    ├── parameter.cr
    ├── path_item.cr
    ├── property.cr
    ├── request_body.cr
    ├── response.cr
    ├── schema.cr
    ├── security_scheme.cr
    ├── server.cr
    └── tag.cr

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 mostly Crystal framework (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] Tags Object
[x] Servers Objec
- [x] ServerVariables Object
[x] Security Object
[ ] Components Object
- [x] Schemas Object
- [x] SecuritySchemes Object
  - [x] Basic
  - [x] Bearer (include JWT)
  - [x] APIKey
  - [x] OAuth2
[ ] 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.

CrystalDoc.info

swagger