{"id":14955557,"url":"https://github.com/zuzannast/swagger_ui_engine","last_synced_at":"2025-10-08T18:04:38.219Z","repository":{"id":51081974,"uuid":"85185120","full_name":"zuzannast/swagger_ui_engine","owner":"zuzannast","description":"Include swagger-ui as rails engine and document your API with simple JSON or YAML files.","archived":false,"fork":false,"pushed_at":"2024-01-20T13:15:08.000Z","size":2478,"stargazers_count":83,"open_issues_count":11,"forks_count":43,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T06:07:01.938Z","etag":null,"topics":["rails-engine","rails-gem","rails5","swagger","swagger-docs","swagger-ui","yaml-files"],"latest_commit_sha":null,"homepage":"https://zuzannast.github.io/swagger_ui_engine/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zuzannast.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-16T10:49:04.000Z","updated_at":"2025-03-05T07:18:45.000Z","dependencies_parsed_at":"2024-06-18T21:37:05.819Z","dependency_job_id":"d54a79af-c1c1-473c-a50c-d30087c41b1f","html_url":"https://github.com/zuzannast/swagger_ui_engine","commit_stats":{"total_commits":109,"total_committers":6,"mean_commits":"18.166666666666668","dds":0.04587155963302747,"last_synced_commit":"c95cf7ea54a2c55d555c678830b32bf3a56ddc8a"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuzannast%2Fswagger_ui_engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuzannast%2Fswagger_ui_engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuzannast%2Fswagger_ui_engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zuzannast%2Fswagger_ui_engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zuzannast","download_url":"https://codeload.github.com/zuzannast/swagger_ui_engine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299832,"owners_count":20916190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rails-engine","rails-gem","rails5","swagger","swagger-docs","swagger-ui","yaml-files"],"created_at":"2024-09-24T13:11:21.947Z","updated_at":"2025-10-08T18:04:33.164Z","avatar_url":"https://github.com/zuzannast.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwaggerUiEngine\n\nInclude [swagger-ui](https://github.com/swagger-api/swagger-ui) as Rails engine and document your API with simple YAML files.\n\n[![Gem Version](https://badge.fury.io/rb/swagger_ui_engine.svg)](https://badge.fury.io/rb/swagger_ui_engine) [![Build Status](https://travis-ci.org/zuzannast/swagger_ui_engine.svg?branch=master)](https://travis-ci.org/zuzannast/swagger_ui_engine) [![Code Climate](https://codeclimate.com/github/zuzannast/swagger_ui_engine/badges/gpa.svg)](https://codeclimate.com/github/zuzannast/swagger_ui_engine)\n\n## Versions\n\nSwagger UI version | Rails version\n------------------ | ----------------\n2.2.10             | \u003e= 4.2, \u003c6\n\n## Features\n* Supports API documentation versioning / multiple APIs documentation\n* Easily configurable Swagger interface and OAuth2 authorization\n* Enables using Swagger interface translations\n* Works with API-only applications\n* Simple, clear and actively maintained :ok_woman:\n\n## Problem\nWorking 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](https://github.com/batdevis/swagger_engine) and [swagger-ui_rails](https://github.com/d4be4st/swagger-ui_rails)) or required adding some extra code for the actual documentation (e.g. [swagger-docs](https://github.com/richhollis/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.\n\n## Installation\n\nAdd to Gemfile\n\n```\ngem 'swagger_ui_engine'\n```\n\nAnd then run:\n\n```\n$ bundle\n```\n\n## Usage\n\n### Mount\n\nAdd to your `config/routes.rb`\n\n```\nmount SwaggerUiEngine::Engine, at: \"/api_docs\"\n```\n\nYou can place this route under `admin_constraint` or other restricted path, or configure basic HTTP authentication.\n\n#### Devise auth\n\n```\nauthenticate :user, lambda { |u| u.admin? } do\n  mount SwaggerUiEngine::Engine, at: \"/api_docs\"\nend\n```\n\n#### Basic HTTP auth\n\nSet admin username and password in an initializer:\n\n```\n# config/initializers/swagger_ui_engine.rb\n\nSwaggerUiEngine.configure do |config|\n  config.admin_username = ENV['ADMIN_USERNAME']\n  config.admin_password = ENV['ADMIN_PASSWORD']\nend\n```\n\n### Initialize\n\n#### Versioned API documentations\n\nSet the path of your json/yaml versioned documentations in an initializer:\n\n```\n# config/initializers/swagger_ui_engine.rb\n\nSwaggerUiEngine.configure do |config|\n  config.swagger_url = {\n    v1: 'api/v1/swagger.yaml',\n    v2: 'api/v2/swagger.yaml',\n  }\nend\n```\n\nand place your main documentation file under `/public/api` path.\n\n#### Single API documentation\n\n**NOTE**: This is a compatibility patch for the `SwaggerUiEngine` gem versions `\u003c= 0.0.5`. It's recommended to version your API documentation from the beginning.\n\nYou can define your main documentation url in a hash value (same way as in the versioned documentations) or pass single string with the url:\n\n```\n# config/initializers/swagger_ui_engine.rb\n\nSwaggerUiEngine.configure do |config|\n  config.swagger_url = 'api/swagger.yaml'\nend\n```\n\n### Configure\nConfig Name | Swagger parameter name | Description\n--- | --- | ---\nconfig.swagger_url | url | The url pointing `swagger.yaml` (Swagger 2.0) as per [OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification/). Accepts a Hash, with API version names as keys and documentation URLs as values. Also accepts a String pointing to documentation for all versions.\nconfig.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).\nconfig.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'.\nconfig.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`.\nconfig.json_editor | jsonEditor | Enables a graphical view for editing complex bodies.  Defaults to `false`.\nconfig.translator_enabled | translations | Enables Swagger Ui translations. Defaults to `false`.\nconfig.validator_enabled | validatorUrl | Enables documentation validator.  Defaults to `false` (`validatorUrl: 'null'`).\n\n#### OAuth2 configuration\nYou can configure OAuth2 default authorization.\n\nConfig Name | Swagger parameter name | Description\n--- | --- | ---\nconfig.oauth_client_id | client_id | Default clientId. MUST be a string\nconfig.oauth_client_secret | client_secret | Default clientSecret. MUST be a string\nconfig.oauth_realm | realm | realm query parameter (for oauth1) added to `authorizationUrl` and `tokenUrl` . MUST be a string\nconfig.oauth_app_name | appName | application name, displayed in authorization popup. MUST be a string\nconfig.oauth_scope_separator | scopeSeparator | scope separator for passing scopes, encoded before calling, default value is a space (encoded value `%20`). MUST be a string\nconfig.oauth_query_string_params | additionalQueryStringParams | Additional query parameters added to `authorizationUrl` and `tokenUrl`. MUST be an object\n\n### Edit your json/yaml files\n\nYou can use [Swagger editor](https://github.com/swagger-api/swagger-editor) to write and validate your Swagger docs.\n\n## Example app\n\nHere's an example use of [SwaggerUiEngine in Rails application](https://github.com/zuzannast/swagger_ui_engine_example).\n\n## Contributing\n\nYou'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.\n\n## License\n\nThis project is available under MIT-LICENSE. :sunny:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuzannast%2Fswagger_ui_engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzuzannast%2Fswagger_ui_engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuzannast%2Fswagger_ui_engine/lists"}