Swagger UI Static Engine

I was documenting my API. I wanted to include Swagger UI as simply as possible.

Swagger UI is schweet, because, as they say:

Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets ... just clone this repo and use the pre-built files in the dist folder

At first, I just copied the dist folder into my /public directory. Awesome! It's self-contained and just works.

But then, I had 25k lines of code in my git repo that, didn't belong there. So, I looked for more elegant ways to include it in my project ...

I found some nice projects like:

The problem is, these projects had fallen out of date. I cloned them and tried to update them, but it was complicated to just, copy the new swagger-ui/dist folder over, because these folks had really wired them up in the asset pipeline and, in order to update them I had to mangle / merge / adapt the Swagger UI quite a bit. I thought, what I really wanted was just, the static files, in a separate git repo, in an engine, that I could keep up to date, edit simply (if later I want to tweak the look of things, etc).

So, that's what I have done here. It's mostly just the Swagger UI dist folder, in the public directory of the engine.

Swagger UI Version

Contains Swagger UI version: 2.1.4

The version number of this RubyGem will mirror Swagger UI's ...

Philosophy

This isn't really a gem that you configure, it's a gem that you fork and modify. I'm purposefully trying to alter the static Swagger UI files, as little as possible. The more mods I make, the harder this will be to keep up with the Swagger UI project. Additionally, there's no way for me to anticipate exactly how I will want to modify the Swagger UI files to customize them for my project. I plan to make any customizations that I want, by editing the files directly in this repo.

Install

config/initializers/swagger_ui_static_engine.rb

SwaggerUiStaticEngine::Engine.mount_path = "/api/docs" # the path to your swagger-ui page, when you have mounted it
SwaggerUiStaticEngine::Engine.swagger_url = "/api/swagger.json" # the path to your swagger.json file

config/routes.rb

Rails.application.routes.draw do
  mount SwaggerUiStaticEngine::Engine, at: '/docs'
end

If you are including this inside another engine (as I am, my 'Api' engine), you will need these extra files:

lib/yourengine.rb

require 'swagger_ui_static_engine'

lib/yourengine/yourengine.rb

module YourEngine
  class Engine < ::Rails::Engine
    # combine this engine's static assets with the static assets of the hosting site
    initializer "static assets" do |app|
      app.middleware.insert_before(::ActionDispatch::Static, ::ActionDispatch::Static, "#{root}/public")
    end
  end
end

Updating

wget https://github.com/swagger-api/swagger-ui/archive/master.zip && mv master.zip swagger-ui-master.zip
unzip swagger-ui-master.zip
cp -R swagger-ui-master/dist/ swagger_ui_static_engine/public
mv swagger_ui_static_engine/public/index.html swagger_ui_static_engine/app/views/swagger_ui_static_engine/index.html.erb
git diff
<edit index.html.erb to view & merge anything that was overwritten>
gem build swagger_ui_static_engine.gemspec
gem push swagger_ui_static_engine-2.1.4.gem