From 4b40fb9efe49cf33f3665ab389574f1a10b2113d Mon Sep 17 00:00:00 2001 From: domaindrivendev Date: Fri, 5 Feb 2016 14:47:55 -0800 Subject: [PATCH] Support multiple swagger documents. Add custom_ui_generator. Update readme --- README.md | 87 ++++++++++- .../swagger_rails/application_controller.rb | 4 + .../swagger_rails/swagger_ui_controller.rb | 6 + .../swagger_rails/swagger_ui/index.html.erb | 4 +- config/routes.rb | 1 + lib/generators/swagger_rails/custom_ui/USAGE | 8 + .../custom_ui/custom_ui_generator.rb | 9 ++ .../custom_ui/files/index.html.erb | 145 ++++++++++++++++++ .../install/install_generator.rb | 4 + .../install/templates/swagger.json | 2 +- .../install/templates/swagger_rails.rb | 4 +- lib/swagger_rails.rb | 3 +- .../config/initializers/swagger_rails.rb | 5 +- spec/dummy/config/routes.rb | 2 +- spec/dummy/config/swagger/v1/swagger.json | 2 +- spec/generators/fixtures/config/routes.rb | 2 + .../swagger_rails/custom_ui_generator_spec.rb | 16 ++ .../swagger_rails/install_generator_spec.rb | 8 + 18 files changed, 298 insertions(+), 14 deletions(-) create mode 100644 lib/generators/swagger_rails/custom_ui/USAGE create mode 100644 lib/generators/swagger_rails/custom_ui/custom_ui_generator.rb create mode 100644 lib/generators/swagger_rails/custom_ui/files/index.html.erb create mode 100644 spec/generators/fixtures/config/routes.rb create mode 100644 spec/generators/swagger_rails/custom_ui_generator_spec.rb diff --git a/README.md b/README.md index d3964e5..c23927b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,85 @@ -# swagger-rails -Seamlessly adds a Swagger to Rails-based API's +swagger-rails +========= + +Seamlessly adds a [Swagger](http://swagger.io/) to Rails-based API's! You create one or more swagger.json files to describe your API and swagger-rails will serve it up along with an embedded version of the [swagger-ui](https://github.com/swagger-api/swagger-ui). This means you can complement your API with a slick discovery UI to assist consumers with their integration efforts. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API! + +And that's not all ... + +Once you have a Web API that can describe itself in Swagger, you've opened the treasure chest of Swagger-based tools including a client generator that can be targeted to a wide range of popular platforms. See [swagger-codegen](https://github.com/swagger-api/swagger-codegen) for more details. + +## Getting Started ## + +1. Add this line to your applications _Gemfile_: + + ```ruby + gem swagger_rails + ``` + +2. Run the install generator + + ```ruby + rails g swagger_rails:install + ``` + +3. Spin up your app and navigate to '/api-docs' + + _This is where your awesome API docs and playground can be viewed_ + +4. Update the sample swagger.json (under config/swagger/v1) to describe your API + + _Swagger is a well thought-out and intuitive format so referring to samples will help in getting started. For some of the finer details, you shoud refer to the spec_ + + * _The Demo JSON: http://petstore.swagger.io/v2/swagger.json_ + * _The Demo UI: http://petstore.swagger.io/_ + * _The Spec.: http://swagger.io/specification/_ + +## How does it Work? ## + +The install generator will add the following entry to your applications _routes.rb_ + + ```ruby + mount SwaggerRails::Engine => '/api-docs' + ``` + +This will wire up routes for the swagger-ui assets and the raw JSON descriptions, all prefixed with "/api-docs". For example, if you navigate to "/api-docs/index.html" you'll get the swagger-ui. If you navigate to "/api-docs/v1/swagger.json", you'll get the sample swagger.json that's installed into your app directory at "config/swagger/v1/swagger.json". + +If you'd like your Swagger resources to appear under a different base path, you can change the Engine mount point from "/api-docs" to something else. + +By default, the swagger-ui will request a service description at "<mount-point>/v1/swagger.json" and then use that to generate the slick documentation and playground UI. If you'd like to change the path to your JSON descriptions or create multiple descriptions, you can change the folder structure and files under "config/swagger". For example, you could describe different versions of your API as follows + + ``` + |-- app + |-- config + |-- swagger + |-- v1 + |-- swagger.json + |-- v2 + |-- swagger.json + |-- v3 + |-- swagger.json + ``` + +This will expose each of those descriptions as JSON endpoints. Next, you'll need to tell swagger-ui which of these endpoints you want to provide documentation for. This can be configured in the initializer that's installed at "config/initializers/swagger_rails": + + ```ruby + SwaggerRails.configure do |c| + + c.swagger_docs = { + 'API V1' => 'v1/swagger.json', + 'API V2' => 'v2/swagger.json', + 'API V3' => 'v3/swagger.json' + } + end + ``` + +Now, if you view the swagger-ui, you'll notice that each of these are available in the select box at the top right of the page, allowing you to navigate between the documentations for each version. + +## Customizing the UI ## + +The swagger-ui provides several options for customizing it's behavior, all of which are documented here https://github.com/swagger-api/swagger-ui#swaggerui. If you need to tweak these or customize the overall look and feel of your swagger-ui, then you'll need to provide your own version of index.html. You can do this with the following generator. + +```ruby +rails g swagger_rails:custom_ui +``` + +This will add a local version that you can customize at "app/views/swagger_rails/swagger_ui/index.html.erb" diff --git a/app/controllers/swagger_rails/application_controller.rb b/app/controllers/swagger_rails/application_controller.rb index 491c3ad..23c2481 100644 --- a/app/controllers/swagger_rails/application_controller.rb +++ b/app/controllers/swagger_rails/application_controller.rb @@ -1,4 +1,8 @@ module SwaggerRails class ApplicationController < ActionController::Base + + def redirect_to_swagger_ui + redirect_to swagger_ui_path + end end end diff --git a/app/controllers/swagger_rails/swagger_ui_controller.rb b/app/controllers/swagger_rails/swagger_ui_controller.rb index 13882cd..f3a392e 100644 --- a/app/controllers/swagger_rails/swagger_ui_controller.rb +++ b/app/controllers/swagger_rails/swagger_ui_controller.rb @@ -2,6 +2,12 @@ module SwaggerRails class SwaggerUiController < ApplicationController def index + @discovery_paths = Hash[ + SwaggerRails.swagger_docs.map do |name, path| + [ name, "#{root_path}#{path}" ] + end + ] + render :index, layout: false end end diff --git a/app/views/swagger_rails/swagger_ui/index.html.erb b/app/views/swagger_rails/swagger_ui/index.html.erb index e72ca9f..c281bec 100644 --- a/app/views/swagger_rails/swagger_ui/index.html.erb +++ b/app/views/swagger_rails/swagger_ui/index.html.erb @@ -33,7 +33,7 @@ if (url && url.length > 1) { url = decodeURIComponent(url[1]); } else { - url = "<%= SwaggerRails.swagger_docs.values.first %>"; + url = "<%= @discovery_paths.values.first %>"; } // Pre load translate... @@ -110,7 +110,7 @@
diff --git a/config/routes.rb b/config/routes.rb index bedd5cf..079d448 100644 --- a/config/routes.rb +++ b/config/routes.rb @@ -1,3 +1,4 @@ SwaggerRails::Engine.routes.draw do + root to: 'application#redirect_to_swagger_ui' get '/index.html', to: 'swagger_ui#index', as: :swagger_ui end diff --git a/lib/generators/swagger_rails/custom_ui/USAGE b/lib/generators/swagger_rails/custom_ui/USAGE new file mode 100644 index 0000000..472b6d9 --- /dev/null +++ b/lib/generators/swagger_rails/custom_ui/USAGE @@ -0,0 +1,8 @@ +Description: + Adds a local version of index.html.erb for customizing the swagger-ui + +Example: + rails generate swagger_rails:custom_ui + + This will create: + app/views/swagger_rails/swagger_ui/index.html.erb diff --git a/lib/generators/swagger_rails/custom_ui/custom_ui_generator.rb b/lib/generators/swagger_rails/custom_ui/custom_ui_generator.rb new file mode 100644 index 0000000..4177abd --- /dev/null +++ b/lib/generators/swagger_rails/custom_ui/custom_ui_generator.rb @@ -0,0 +1,9 @@ +module SwaggerRails + class CustomUiGenerator < Rails::Generators::Base + source_root File.expand_path('../files', __FILE__) + + def add_custom_index + copy_file('index.html.erb', 'app/views/swagger_rails/swagger_ui/index.html.erb') + end + end +end diff --git a/lib/generators/swagger_rails/custom_ui/files/index.html.erb b/lib/generators/swagger_rails/custom_ui/files/index.html.erb new file mode 100644 index 0000000..c281bec --- /dev/null +++ b/lib/generators/swagger_rails/custom_ui/files/index.html.erb @@ -0,0 +1,145 @@ + + + + + Swagger UI + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
 
+
+ + diff --git a/lib/generators/swagger_rails/install/install_generator.rb b/lib/generators/swagger_rails/install/install_generator.rb index d3b94ac..8a7329d 100644 --- a/lib/generators/swagger_rails/install/install_generator.rb +++ b/lib/generators/swagger_rails/install/install_generator.rb @@ -12,5 +12,9 @@ module SwaggerRails def add_initializer template('swagger_rails.rb', 'config/initializers/swagger_rails.rb') end + + def add_routes + route("mount SwaggerRails::Engine => '/api-docs'") + end end end diff --git a/lib/generators/swagger_rails/install/templates/swagger.json b/lib/generators/swagger_rails/install/templates/swagger.json index 1b7597b..e18a96f 100644 --- a/lib/generators/swagger_rails/install/templates/swagger.json +++ b/lib/generators/swagger_rails/install/templates/swagger.json @@ -3,7 +3,7 @@ "info": { "version": "0.0.0", "title": "[Enter a description for your API here]", - "description": "The docs below are powered by the default swagger.json installed with swagger_rails. Please update it to describe your API. See here for the complete swagger spec - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md" + "description": "The docs below are powered by the default swagger.json that gets installed with swagger_rails. You'll need to update it to describe your API. See here for the complete swagger spec - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md" }, "paths": { "/a/sample/resource": { diff --git a/lib/generators/swagger_rails/install/templates/swagger_rails.rb b/lib/generators/swagger_rails/install/templates/swagger_rails.rb index 805b9ae..050d919 100644 --- a/lib/generators/swagger_rails/install/templates/swagger_rails.rb +++ b/lib/generators/swagger_rails/install/templates/swagger_rails.rb @@ -1,8 +1,8 @@ SwaggerRails.configure do |c| - # List the names and paths of Swagger + # List the names and paths (relative to config/swagger) of Swagger # documents you'd like to expose in your swagger-ui c.swagger_docs = { - 'API V1' => '/swagger/v1/swagger.json' + 'API V1' => 'v1/swagger.json' } end diff --git a/lib/swagger_rails.rb b/lib/swagger_rails.rb index 856263a..7ba7bde 100644 --- a/lib/swagger_rails.rb +++ b/lib/swagger_rails.rb @@ -9,9 +9,8 @@ module SwaggerRails class << self attr_accessor :swagger_docs - #Defaults @@swagger_docs = { - 'V1' => '/swagger/v1/swagger.json' + 'V1' => 'v1/swagger.json' } end end diff --git a/spec/dummy/config/initializers/swagger_rails.rb b/spec/dummy/config/initializers/swagger_rails.rb index 9a2d6c8..050d919 100644 --- a/spec/dummy/config/initializers/swagger_rails.rb +++ b/spec/dummy/config/initializers/swagger_rails.rb @@ -1,9 +1,8 @@ SwaggerRails.configure do |c| - # List the names and paths of Swagger + # List the names and paths (relative to config/swagger) of Swagger # documents you'd like to expose in your swagger-ui c.swagger_docs = { - 'API V1' => '/swagger/v1/swagger.json', - 'API V2' => '/swagger/v2/swagger.json' + 'API V1' => 'v1/swagger.json' } end diff --git a/spec/dummy/config/routes.rb b/spec/dummy/config/routes.rb index 4bd609e..8264b95 100644 --- a/spec/dummy/config/routes.rb +++ b/spec/dummy/config/routes.rb @@ -1,4 +1,4 @@ Rails.application.routes.draw do + mount SwaggerRails::Engine => '/api-docs' - mount SwaggerRails::Engine => '/swagger' end diff --git a/spec/dummy/config/swagger/v1/swagger.json b/spec/dummy/config/swagger/v1/swagger.json index 830009e..e18a96f 100644 --- a/spec/dummy/config/swagger/v1/swagger.json +++ b/spec/dummy/config/swagger/v1/swagger.json @@ -3,7 +3,7 @@ "info": { "version": "0.0.0", "title": "[Enter a description for your API here]", - "description": "The docs below are powered by the default swagger.json that was installed with swagger_rails. You can update it to describe your API. See here for the complete swagger spec - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md" + "description": "The docs below are powered by the default swagger.json that gets installed with swagger_rails. You'll need to update it to describe your API. See here for the complete swagger spec - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md" }, "paths": { "/a/sample/resource": { diff --git a/spec/generators/fixtures/config/routes.rb b/spec/generators/fixtures/config/routes.rb new file mode 100644 index 0000000..1daf9a4 --- /dev/null +++ b/spec/generators/fixtures/config/routes.rb @@ -0,0 +1,2 @@ +Rails.application.routes.draw do +end diff --git a/spec/generators/swagger_rails/custom_ui_generator_spec.rb b/spec/generators/swagger_rails/custom_ui_generator_spec.rb new file mode 100644 index 0000000..d0f6b97 --- /dev/null +++ b/spec/generators/swagger_rails/custom_ui_generator_spec.rb @@ -0,0 +1,16 @@ +require 'rails_helper' +require 'generators/swagger_rails/custom_ui/custom_ui_generator' + +describe SwaggerRails::CustomUiGenerator do + include GeneratorSpec::TestCase + destination File.expand_path('../tmp', __FILE__) + + before(:all) do + prepare_destination + run_generator + end + + it 'creates a local version of index.html.erb' do + assert_file('app/views/swagger_rails/swagger_ui/index.html.erb') + end +end diff --git a/spec/generators/swagger_rails/install_generator_spec.rb b/spec/generators/swagger_rails/install_generator_spec.rb index 41e6836..5a1cdff 100644 --- a/spec/generators/swagger_rails/install_generator_spec.rb +++ b/spec/generators/swagger_rails/install_generator_spec.rb @@ -7,6 +7,9 @@ describe SwaggerRails::InstallGenerator do before(:all) do prepare_destination + config_dir = File.expand_path('../../fixtures/config', __FILE__) + FileUtils.cp_r(config_dir, destination_root) + run_generator end @@ -17,4 +20,9 @@ describe SwaggerRails::InstallGenerator do it 'creates a swagger_rails initializer' do assert_file('config/initializers/swagger_rails.rb') end + + it 'wires up the swagger routes' do + pending('not sure how to test this') + this_should_not_get_executed + end end