Coder Social home page Coder Social logo

koheisg / swagger_ui_engine Goto Github PK

View Code? Open in Web Editor NEW

This project forked from azelenets/swagger_ui_engine

0.0 0.0 0.0 2.42 MB

Include swagger-ui as rails engine and document your API with simple JSON or YAML files.

Home Page: https://zuzannast.github.io/swagger_ui_engine/

License: MIT License

JavaScript 95.93% Ruby 0.51% CSS 0.01% HTML 3.55%

swagger_ui_engine's Introduction

SwaggerUiEngine

Include swagger-ui as Rails engine and document your API with simple YAML files.

Gem Version Build Status Code Climate

Versions

Swagger UI version Rails version
2.2.10 >= 6

Features

  • Supports API documentation versioning / multiple APIs documentation
  • Easily configurable Swagger interface and OAuth2 authorization
  • Enables using Swagger interface translations
  • Works with API-only applications
  • Simple, clear and actively maintained ๐Ÿ™†โ€โ™€๏ธ

Problem

Working on a Rails API, I've wanted to document my endpoints in the clearest and easiest way possible. My goal was to have the documentation separated from the actual codebase and to have a web UI version of Swagger for testing and reading it. Using Rails 5 default API, I didn't need to include Grape, so I took a look into some other existing solutions. Most of them were no longer supported (e.g. swagger_engine and swagger-ui_rails) or required adding some extra code for the actual documentation (e.g. swagger-docs). Also, none of them supported Swagger web UI configuration, so I decided to write and maintain a gem on my own that would allow others to include Swagger web UI as Rails engine and support writing simple documentation in YAML files.

Installation

Add to Gemfile

gem 'swagger_ui_engine'

And then run:

$ bundle

Usage

Mount

Add to your config/routes.rb

mount SwaggerUiEngine::Engine, at: "/api_docs"

You can place this route under admin_constraint or other restricted path, or configure basic HTTP authentication.

Devise auth

authenticate :user, lambda { |u| u.admin? } do
  mount SwaggerUiEngine::Engine, at: "/api_docs"
end

Basic HTTP auth

Set admin username and password in an initializer:

# config/initializers/swagger_ui_engine.rb

SwaggerUiEngine.configure do |config|
  config.admin_username = ENV['ADMIN_USERNAME']
  config.admin_password = ENV['ADMIN_PASSWORD']
end

Initialize

Versioned API documentations

Set the path of your json/yaml versioned documentations in an initializer:

# config/initializers/swagger_ui_engine.rb

SwaggerUiEngine.configure do |config|
  config.swagger_url = {
    v1: 'api/v1/swagger.yaml',
    v2: 'api/v2/swagger.yaml',
  }
end

and place your main documentation file under /public/api path.

Single API documentation

NOTE: This is a compatibility patch for the SwaggerUiEngine gem versions <= 0.0.5. It's recommended to version your API documentation from the beginning.

You can define your main documentation url in a hash value (same way as in the versioned documentations) or pass single string with the url:

# config/initializers/swagger_ui_engine.rb

SwaggerUiEngine.configure do |config|
  config.swagger_url = 'api/swagger.yaml'
end

Configure

Config Name Swagger parameter name Description
config.swagger_url url The url pointing swagger.yaml (Swagger 2.0) as per OpenAPI Spec. Accepts a Hash, with API version names as keys and documentation URLs as values. Also accepts a String pointing to documentation for all versions.
config.doc_expansion docExpansion Controls how the API listing is displayed. It can be set to 'none' (default), 'list' (shows operations for each resource), or 'full' (fully expanded: shows operations and their details).
config.model_rendering defaultModelRendering Controls how models are shown when the API is first rendered. It can be set to 'model' or 'schema', and the default is 'schema'.
config.request_headers showRequestHeaders Whether or not to show the headers that were sent when making a request via the 'Try it out!' option. Defaults to false.
config.json_editor jsonEditor Enables a graphical view for editing complex bodies. Defaults to false.
config.translator_enabled translations Enables Swagger Ui translations. Defaults to false.
config.validator_enabled validatorUrl Enables documentation validator. Defaults to false (validatorUrl: 'null').

OAuth2 configuration

You can configure OAuth2 default authorization.

Config Name Swagger parameter name Description
config.oauth_client_id client_id Default clientId. MUST be a string
config.oauth_client_secret client_secret Default clientSecret. MUST be a string
config.oauth_realm realm realm query parameter (for oauth1) added to authorizationUrl and tokenUrl . MUST be a string
config.oauth_app_name appName application name, displayed in authorization popup. MUST be a string
config.oauth_scope_separator scopeSeparator scope separator for passing scopes, encoded before calling, default value is a space (encoded value %20). MUST be a string
config.oauth_query_string_params additionalQueryStringParams Additional query parameters added to authorizationUrl and tokenUrl. MUST be an object

Edit your json/yaml files

You can use Swagger editor to write and validate your Swagger docs.

Example app

Here's an example use of SwaggerUiEngine in Rails application.

Contributing

You're very much welcome to contribute to this repository. Start by creating a Github issue and describing your change thoroughly. If you decide to publish a pull request, please make sure it points to the latest versioned branch instead of master.

License

This project is available under MIT-LICENSE. โ˜€๏ธ

swagger_ui_engine's People

Contributors

akosipc avatar azelenets avatar jonmidhir avatar kdiogenes avatar shekhar-patil avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.