Add Swagger documentation (#46)

duffn · web-flow · commit c8f94f106c44 · 2023-03-26T14:45:26.000-04:00
* Adds Swagger documentation

* Add Swagger spec
diff --git a/Gemfile b/Gemfile
@@ -47,6 +47,7 @@ gem 'bootsnap', require: false
 # gem "image_processing", "~> 1.2"
 
 gem 'grape', '~> 1.7'
+gem 'grape-swagger'
 
 group :development, :test do
   # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -118,6 +118,8 @@ GEM
       mustermann-grape (~> 1.0.0)
       rack (>= 1.3.0)
       rack-accept
+    grape-swagger (1.6.0)
+      grape (~> 1.3)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
     importmap-rails (1.1.1)
@@ -297,6 +299,7 @@ DEPENDENCIES
   capybara
   debug
   grape (~> 1.7)
+  grape-swagger
   importmap-rails
   jbuilder
   pg (~> 1.1)
diff --git a/README.md b/README.md
@@ -19,4 +19,5 @@ bundle install
 rails s
 ```
 
-Try http://localhost:3000/api/ping or http://localhost:3000/api/protected/ping with _username_ and _password_.
+- Try http://localhost:3000/api/ping or http://localhost:3000/api/protected/ping with _username_ and _password_.
+- View Swagger docs at http://localhost:3000/swagger.
diff --git a/app/api/acme/post.rb b/app/api/acme/post.rb
@@ -1,6 +1,9 @@
 module Acme
   class Post < Grape::API
     desc 'Creates a spline that can be reticulated.'
+    params do
+      optional :reticulated, type: Boolean, documentation: { param_type: 'body' }
+    end
     resource :spline do
       post do
         { reticulated: params[:reticulated] }
diff --git a/app/api/api.rb b/app/api/api.rb
@@ -6,4 +6,5 @@ class API < Grape::API
   mount Acme::Protected
   mount Acme::Post
   mount Acme::Headers
+  add_swagger_documentation info: { title: 'grape-on-rails' }
 end
diff --git a/gemfiles/rails_6.gemfile b/gemfiles/rails_6.gemfile
@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 gem 'bootsnap', require: false
 gem 'grape', '~> 1.7'
+gem 'grape-swagger'
 gem 'importmap-rails'
 gem 'jbuilder'
 gem 'pg', '~> 1.1'
diff --git a/gemfiles/rails_6_1.gemfile b/gemfiles/rails_6_1.gemfile
@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 gem 'bootsnap', require: false
 gem 'grape', '~> 1.7'
+gem 'grape-swagger'
 gem 'importmap-rails'
 gem 'jbuilder'
 gem 'pg', '~> 1.1'
diff --git a/gemfiles/rails_7.gemfile b/gemfiles/rails_7.gemfile
@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 gem 'bootsnap', require: false
 gem 'grape', '~> 1.7'
+gem 'grape-swagger'
 gem 'importmap-rails'
 gem 'jbuilder'
 gem 'pg', '~> 1.1'
diff --git a/gemfiles/rails_edge.gemfile b/gemfiles/rails_edge.gemfile
@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 gem 'bootsnap', require: false
 gem 'grape', '~> 1.7'
+gem 'grape-swagger'
 gem 'importmap-rails'
 gem 'jbuilder'
 gem 'pg', '~> 1.1'
diff --git a/public/swagger/index.html b/public/swagger/index.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="SwaggerUI" />
+    <title>SwaggerUI</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.18.1/swagger-ui.css" />
+</head>
+
+<body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@4.18.1/swagger-ui-bundle.js" crossorigin></script>
+    <script src="https://unpkg.com/swagger-ui-dist@4.18.1/swagger-ui-standalone-preset.js" crossorigin></script>
+    <script>
+        window.onload = () => {
+            window.ui = SwaggerUIBundle({
+                url: '/api/swagger_doc',
+                dom_id: '#swagger-ui',
+                presets: [
+                    SwaggerUIBundle.presets.apis,
+                    SwaggerUIStandalonePreset
+                ],
+                layout: "StandaloneLayout",
+            });
+        };
+    </script>
+</body>
+
+</html>
diff --git a/spec/features/swagger_spec.rb b/spec/features/swagger_spec.rb
@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe 'Swagger', js: true, type: :feature do
+  before :each do
+    visit '/swagger'
+  end
+  it 'displays Swagger page' do
+    expect(page.find('.title')).to have_content 'grape-on-rails'
+  end
+end
