Add SwaggerUi to replace Apiary (#517)

* Add SwaggerUi to replace Apiary, expose api-doc and add basic-auth
* Update README.md

.env.sample

@@ -8,3 +8,5 @@ PASSWORD_RESET_URL=http://127.0.0.1:3000
 SENDGRID_API_KEY=
 SERVER_HOST=localhost
 S3_BUCKET_NAME=
+SWAGGER_USERNAME=username
+SWAGGER_PASSWORD=password

Gemfile

@@ -26,6 +26,8 @@ gem 'pg', '~> 1.5'
 gem 'puma', '~> 6.4'
 gem 'pundit', '~> 2.3'
 gem 'rack-cors', '~> 2.0'
+gem 'rswag-api', '~> 2.11.0'
+gem 'rswag-ui', '~> 2.11.0'
 gem 'sass-rails', '~> 6.0.0'
 gem 'sendgrid', '~> 1.2.4'
 gem 'sprockets', '~> 4.2.1'

Gemfile.lock

@@ -415,6 +415,11 @@ GEM
       rspec-mocks (~> 3.12)
       rspec-support (~> 3.12)
     rspec-support (3.12.1)
+    rswag-api (2.11.0)
+      railties (>= 3.1, < 7.2)
+    rswag-ui (2.11.0)
+      actionpack (>= 3.1, < 7.2)
+      railties (>= 3.1, < 7.2)
     rubocop (1.57.2)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -557,6 +562,8 @@ DEPENDENCIES
   rspec-openapi (~> 0.9)
   rspec-rails (~> 6.0)
   rspec-retry!
+  rswag-api (~> 2.11.0)
+  rswag-ui (~> 2.11.0)
   rubocop (~> 1.57)
   rubocop-factory_bot (~> 2.24)
   rubocop-performance (~> 1.19)

README.md

@@ -99,7 +99,8 @@ To illustrate, `bin/rails console` will run the console in the docker container
 - [Rails Best Practices](https://github.com/flyerhzm/rails_best_practices) for rails linting
 - [Reek](https://github.com/troessner/reek) for ruby linting
 - [RSpec](https://github.com/rspec/rspec) for testing
-- [RSpec OpenAPI](https://github.com/exoego/rspec-openapi) for API documentation
+- [RSpec OpenAPI](https://github.com/exoego/rspec-openapi) for generating API documentation
+- [Rswag](https://github.com/rswag/rswag) for expose API documentation
 - [Rubocop](https://github.com/bbatsov/rubocop/) for ruby linting
 - [Sendgrid](https://github.com/stephenb/sendgrid) for sending mails
 - [Shoulda Matchers](https://github.com/thoughtbot/shoulda-matchers) adds other testing matchers
@@ -117,9 +118,8 @@ To illustrate, `bin/rails console` will run the console in the docker container
 
 ## Api Docs
 
-https://railsapibasers.docs.apiary.io/
-
-With [RSpec API Doc Generator](https://github.com/exoego/rspec-openapi) you can generate the docs after writing requests specs.
+- [RSpec API Doc Generator](https://github.com/exoego/rspec-openapi) you can generate the docs after writing requests specs.
+- [Rswag](https://github.com/rswag/rswag) you can expose the generated docs.
 
 See [api_documentation](./docs/api_documentation.md) docs for more info.
 

config/initializers/rswag_api.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Rswag::Api.configure do |c|
+  # Specify a root folder where Swagger JSON files are located
+  # This is used by the Swagger middleware to serve requests for API descriptions
+  # NOTE: If you're using rswag-specs to generate Swagger, you'll need to ensure
+  # that it's configured to generate files in the same folder
+  c.swagger_root = "#{Rails.root}/doc"
+
+  # Inject a lambda function to alter the returned Swagger prior to serialization
+  # The function will have access to the rack env for the current request
+  # For example, you could leverage this to dynamically assign the "host" property
+  #
+  # c.swagger_filter = lambda { |swagger, env| swagger['host'] = env['HTTP_HOST'] }
+end

config/initializers/rswag_ui.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+Rswag::Ui.configure do |c|
+  # List the Swagger endpoints that you want to be documented through the
+  # swagger-ui. The first parameter is the path (absolute or relative to the UI
+  # host) to the corresponding endpoint and the second is a title that will be
+  # displayed in the document selector.
+  # NOTE: If you're using rspec-api to expose Swagger files
+  # (under swagger_root) as JSON or YAML endpoints, then the list below should
+  # correspond to the relative paths for those endpoints.
+
+  c.swagger_endpoint '/api-docs/openapi.yaml', 'API V1 Docs'
+
+  # Add Basic Auth in case your API is private
+  c.basic_auth_enabled = true
+  c.basic_auth_credentials ENV.fetch('SWAGGER_USERNAME', 'username'), ENV.fetch('SWAGGER_PASSWORD', 'password')
+end

config/routes.rb

@@ -26,4 +26,6 @@
       end
     end
   end
+  mount Rswag::Ui::Engine => '/api-docs'
+  mount Rswag::Api::Engine => '/api-docs'
 end

docs/api_documentation.md

@@ -9,6 +9,16 @@ For the action to update the docs make sure to set the `PUSH_KEY` secret so the
 2. Add a "secret" to the repo with name `PUSH_KEY` and value the generated file `deploy_key`.
 3. Add a "deploy key" to the repo with title `GitHub Actions` and value the generated file `deploy_key.pub`. Make sure to tick the "Allow write access" checkbox.
 
+### SwaggerUI
+The autogenerated documentation is exposed using Swagger UI, this documentation can be found in the `/api-docs` path.
+
+The route is protected using basic auth by default, this can be disabled in the initializer file `rswag_ui.rb`
+```ruby
+  c.basic_auth_enabled = true
+  c.basic_auth_credentials ENV.fetch('SWAGGER_USERNAME', 'username'), ENV.fetch('SWAGGER_PASSWORD', 'password')
+```
+the access data can also be defined using the environment variables `SWAGGER_USERNAME` and `SWAGGER_PASSWORD`. 
+
 ### Ignoring specs
 To ignore specs that we don't want in the final API documentation we can add the `openapi: false` option to the spec like so:
 ```ruby