WIP swagger foundations

Gemfile

@@ -151,6 +151,9 @@ gem 'bootsnap', '~> 1.4.0', require: false
 # Bulk inserts and upserts
 gem 'activerecord-import'
 
+# Swagger API
+gem "openstax_swagger", github: 'openstax/swagger-rails', ref: '9bff4962b31e142debbc62390f1fd3adab3af055'
+
 group :development, :test do
   # Get env variables from .env file
   gem 'dotenv-rails'

Gemfile.lock

@@ -8,6 +8,17 @@ GIT
       json
       typhoeus (~> 1.0, >= 1.0.1)
 
+GIT
+  remote: https://github.com/openstax/swagger-rails.git
+  revision: 9bff4962b31e142debbc62390f1fd3adab3af055
+  ref: 9bff4962b31e142debbc62390f1fd3adab3af055
+  specs:
+    openstax_swagger (0.1.0)
+      oj
+      oj_mimic_json
+      rails (~> 5.2.3)
+      swagger-blocks
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -451,6 +462,7 @@ GEM
       actionpack (>= 4.0)
       activesupport (>= 4.0)
       sprockets (>= 3.0.0)
+    swagger-blocks (3.0.0)
     test_xml (0.1.8)
       diffy (~> 3.0)
       nokogiri (>= 1.3.2)
@@ -546,6 +558,7 @@ DEPENDENCIES
   openstax_api
   openstax_healthcheck
   openstax_rescue_from
+  openstax_swagger!
   openstax_utilities
   parallel_tests
   pg

README.md

@@ -80,6 +80,14 @@ Then
 $> docker-compose run api bundle exec rspec
 ```
 
+If you update the Gemfile...
+
+```bash
+$> docker-compose down
+$> docker-compose run api bundle install
+$> docker-compose up
+```
+
 ### Install everything yourself
 
 1. Install a ruby version manager on your machine, such as rbenv or rvm

app/controllers/api/v1/swagger_controller.rb

@@ -0,0 +1,49 @@
+require 'uri'
+
+class Api::V1::SwaggerController < OpenStax::Api::V1::ApiController
+  include ::Swagger::Blocks
+
+  ACCEPT_HEADER = 'application/json'
+  BASE_PATH = '/api/v1'
+
+  swagger_root do
+    key :swagger, '2.0'
+    info do
+      key :version, '1.0.0'
+      key :title, 'OpenStax Exercises API'
+      key :description, <<~DESC
+        The exercises API for OpenStax.
+
+        Requests to this API should include `#{ACCEPT_HEADER}` in the `Accept` header.
+
+        The desired API version is specified in the request URL, e.g. `[domain]#{BASE_PATH}/highlights`. \
+        While the API does support a default version, that version will change over \
+        time and therefore should not be used in production code!
+      DESC
+      key :termsOfService, 'https://openstax.org/tos'
+      contact do
+        key :name, 'support@openstax.org'
+      end
+      license do
+        key :name, 'MIT'
+      end
+    end
+    tag do
+      key :name, 'Exercises'
+      key :description, 'Exercises endpoints'
+    end
+    key :basePath, BASE_PATH
+    key :consumes, [ACCEPT_HEADER]
+    key :produces, ['application/json']
+  end
+
+  SWAGGERED_CLASSES = [
+    Api::V1::SwaggerResponses,
+    Api::V1::UsersSwagger,
+    self,
+  ].freeze
+
+  def json
+    render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
+  end
+end

app/controllers/api/v1/swagger_responses.rb

@@ -0,0 +1,64 @@
+module Api::V0::SwaggerResponses
+  include Swagger::Blocks
+  include OpenStax::Swagger::SwaggerBlocksExtensions
+
+  swagger_schema :Error do
+    property :status_code do
+      key :type, :integer
+      key :description, "The HTTP status code"
+    end
+    property :messages do
+      key :type, :array
+      key :description, "The error messages, if any"
+      items do
+        key :type, :string
+      end
+    end
+  end
+
+  module AuthenticationError
+    def self.extended(base)
+      base.response 401 do
+        key :description, 'Not authenticated.  The user is not authenticated.'
+      end
+    end
+  end
+
+  module ForbiddenError
+    def self.extended(base)
+      base.response 403 do
+        key :description, 'Forbidden.  The user is not allowed to perform the requested action.'
+      end
+    end
+  end
+
+  module NotFoundError
+    def self.extended(base)
+      base.response 404 do
+        key :description, 'Not found'
+      end
+    end
+  end
+
+  module UnprocessableEntityError
+    def self.extended(base)
+      base.response 422 do
+        key :description, 'Could not process request'
+        schema do
+          key :'$ref', :Error
+        end
+      end
+    end
+  end
+
+  module ServerError
+    def self.extended(base)
+      base.response 500 do
+        key :description, 'Server error.'
+        schema do
+          key :'$ref', :Error
+        end
+      end
+    end
+  end
+end