apia-open_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f5de7b599466adb38eeeb825b2688ca64460a5c10c517141775af93355d35f6
+  data.tar.gz: 285a0dfa241e201f1df2370553294cd7514b9ef339060a3f9b0ff5d3268a7064
+SHA512:
+  metadata.gz: cce09e236df6739ae7d4480597d4dbe012c901bd3aa5e4ebc38f49c19915917997737f3b5d2bee4fc09ec82a9223842fb84793b7cf746994dc2f37dac7d115cb
+  data.tar.gz: e02b8c2ff50507d65cb45a0b67ab189782174e5c95dae20b29d11c671e3562e1c6dcf80c1950fad5276eff3cf4fdc6975b761ac81f3b8806379b225c6cec91e2

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in apia-open_api.gemspec
+gemspec
+
+gem "apia", "~> 3.5"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+
+group :test do
+  gem "pry"
+  gem "simplecov", require: false
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Krystal Hosting Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Apia OpenAPI Specification
+
+This gem can generate an [OpenAPI](https://www.openapis.org/) compatible schema from an API implemented using [Apia](https://github.com/krystal/apia).
+
+## Installation
+
+TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+
+## Usage
+
+The schema can be mounted in much the same way as an [Apia API](https://github.com/krystal/apia) itself.
+
+For example, for a Ruby on Rails application:
+
+```ruby
+module MyApp
+  class Application < Rails::Application
+
+    config.middleware.use Apia::OpenApi::Rack,
+                          api_class: "CoreAPI::Base",
+                          schema_path: "/core/v1/schema/openapi.json",
+                          base_url: "http://katapult-api.localhost/core/v1"
+
+  end
+end
+```
+
+Where `CoreAPI::Base` is the name of the API class that inherits from `Apia::API`.
+
+## Generating a client library from the spec
+
+It's possible to generate a client library from the generated OpenAPI schema using [OpenAPI Generator](https://openapi-generator.tech/).
+
+For example we can generate a Ruby client with the following:
+
+```bash
+brew install openapi-generator
+openapi-generator generate -i openapi.json -g ruby -o openapi-client --additional-properties=gemName=myapp-openapi-client,moduleName=MyAppOpenAPIClient
+```
+
+The generated client will be in the `openapi-client` directory and will contain a readme with instructions on how to use it.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+In `/examples` there is an example Apia API application that can be used to try out the gem.
+
+Run `rackup` from the root of `/examples` to start the [rack app](https://github.com/rack/rack) running the example API.
+To view the generated OpenAPI schema, visit: http://127.0.0.1:9292/core/v1/schema/openapi.json
+`/examples/config.ru` shows how to mount the schema endpoint.
+
+The generated schema can be viewed, validated and tried out using the online [Swagger Editor](https://editor.swagger.io/). You'll need to add the bearer token to the swagger editor to authenticate the requests. After that, they should work as expected. The bearer token is defined in main_authenticator.rb.
+
+Currently the online swagger-editor only allows the OpenAPI schema v3.0.0. But it's also possible to run the swagger-editor locally, which allows us to check against v3.1.0.
+
+e.g with this docker-compose.yml file:
+
+```yml
+version: "3.3"
+services:
+  swagger-editor:
+    image: swaggerapi/swagger-editor:next-v5
+    container_name: "swagger-editor"
+    ports:
+      - "8081:80"
+```
+
+Run `docker-compose up` and visit http://localhost:8081 to view the swagger editor.
+
+### Tests and Linting
+
+- `bin/rspec`
+- `bin/rubocop`
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Releasing a new version
+
+TODO: Write instructions for releasing a new version of the gem.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/krystal/apia-open_api.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/apia-open_api.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/apia/open_api/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "apia-open_api"
+  spec.version = Apia::OpenApi::VERSION
+  spec.authors = ["Paul Sturgess"]
+
+  spec.summary = "Apia OpenAPI spec generator"
+  spec.homepage = "https://github.com/krystal/apia-openapi"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/krystal/apia-openapi"
+  spec.metadata["changelog_uri"] = "https://github.com/krystal/apia-openapi/changelog.md"
+
+  spec.metadata["rubygems_mfa_required"] = "false" # rubocop:disable Gemspec/RequireMFA (enabling MFA means we cannot auto publish via the CI)
+
+  spec.files = Dir[File.join("lib", "**", "*.rb")] +
+               Dir["{*.gemspec,Gemfile,Rakefile,README.*,LICENSE*}"]
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(/\Aexe\//) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activesupport", ">= 6"
+end

data/lib/apia/open_api/helpers.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# A collection of 'utility' methods used across the various OpenAPI::Objects
+module Apia
+  module OpenApi
+    module Helpers
+
+      # A component schema is a re-usable schema that can be referenced by other parts of the spec
+      # e.g. { "$ref": "#/components/schemas/PaginationObject" }
+      def add_to_components_schemas(definition, id, **schema_opts)
+        return true unless @spec.dig(:components, :schemas, id).nil?
+
+        component_schema = {}
+        @spec[:components][:schemas][id] = component_schema
+        Objects::Schema.new(
+          spec: @spec,
+          definition: definition,
+          schema: component_schema,
+          id: id,
+          **schema_opts
+        ).add_to_spec
+
+        return true if component_schema.present?
+
+        @spec[:components][:schemas].delete(id)
+        false
+      end
+
+      def convert_type_to_open_api_data_type(type)
+        case type.klass.to_s
+        when "Apia::Scalars::String", "Apia::Scalars::Base64", "Apia::Scalars::Date"
+          "string"
+        when "Apia::Scalars::Integer", "Apia::Scalars::UnixTime"
+          "integer"
+        when "Apia::Scalars::Decimal"
+          "number"
+        when "Apia::Scalars::Boolean"
+          "boolean"
+        else
+          raise "Unknown Apia type #{type.klass} mapping to OpenAPI type"
+        end
+      end
+
+      def generate_scalar_schema(definition)
+        type = definition.type
+        schema = {
+          type: convert_type_to_open_api_data_type(type)
+        }
+        schema[:description] = definition.description if definition.description.present?
+        schema[:format] = "float" if type.klass == Apia::Scalars::Decimal
+        schema[:format] = "date" if type.klass == Apia::Scalars::Date
+        schema
+      end
+
+      def generate_schema_ref(definition, id: nil, **schema_opts)
+        id ||= generate_id_from_definition(definition.type.klass.definition)
+        success = add_to_components_schemas(definition, id, **schema_opts)
+
+        if success
+          { "$ref": "#/components/schemas/#{id}" }
+        else # no properties were defined, so just declare an object with unknown properties
+          { type: "object" }
+        end
+      end
+
+      def generate_id_from_definition(definition)
+        definition.id.split("/").last
+      end
+
+      def formatted_description(description)
+        return description if description.end_with?(".")
+
+        "#{description}."
+      end
+
+    end
+  end
+end

data/lib/apia/open_api/objects/bearer_security_scheme.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# The BearerSecurityScheme object defines the required spec for authentication via a bearer token.
+#
+# "components": {
+#   "securitySchemes": {
+#     "CoreAPI_Authenticator": {
+#       "scheme": "bearer",
+#       "type": "http"
+#     }
+#   }
+# },
+# "security": [
+#   {
+#     "CoreAPI_Authenticator": []
+#   }
+# ]
+
+module Apia
+  module OpenApi
+    module Objects
+      class BearerSecurityScheme
+
+        include Apia::OpenApi::Helpers
+
+        def initialize(spec:, authenticator:)
+          @spec = spec
+          @authenticator = authenticator
+        end
+
+        def add_to_spec
+          @spec[:components][:securitySchemes] ||= {}
+          @spec[:components][:securitySchemes][generate_id_from_definition(@authenticator.definition)] = {
+            scheme: "bearer",
+            type: "http"
+          }
+
+          @spec[:security] << {
+            generate_id_from_definition(@authenticator.definition) => []
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/apia/open_api/objects/parameters.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Parameters describe the arguments that can be passed to an endpoint via the query string.
+# We only declare these for GET requests, otherwise we define a request body.
+#
+# "parameters": [
+#   {
+#     "name": "data_center[id]",
+#     "in": "query",
+#     "schema": {
+#       "type": "string"
+#     }
+#   },
+#   {
+#     "name": "data_center[permalink]",
+#     "in": "query",
+#     "schema": {
+#       "type": "string"
+#     }
+#   }
+# ]
+module Apia
+  module OpenApi
+    module Objects
+      class Parameters
+
+        include Apia::OpenApi::Helpers
+
+        def initialize(spec:, argument:, route_spec:)
+          @spec = spec
+          @argument = argument
+          @route_spec = route_spec
+        end
+
+        def add_to_spec
+          if @argument.type.argument_set?
+            generate_argument_set_params
+          elsif @argument.array?
+            if @argument.type.enum? || @argument.type.object?
+              items = generate_schema_ref(@argument)
+            else
+              items = generate_scalar_schema(@argument)
+            end
+
+            param = {
+              name: "#{@argument.name}[]",
+              in: "query",
+              schema: {
+                type: "array",
+                items: items
+              }
+            }
+            param[:description] = @argument.description if @argument.description.present?
+            param[:required] = true if @argument.required?
+            add_to_parameters(param)
+          elsif @argument.type.enum?
+            param = {
+              name: @argument.name.to_s,
+              in: "query",
+              schema: generate_schema_ref(@argument)
+            }
+            param[:description] = @argument.description if @argument.description.present?
+            param[:required] = true if @argument.required?
+            add_to_parameters(param)
+          else
+            param = {
+              name: @argument.name.to_s,
+              in: "query",
+              schema: generate_scalar_schema(@argument)
+            }
+            param[:description] = @argument.description if @argument.description.present?
+            param[:required] = true if @argument.required?
+            add_to_parameters(param)
+          end
+        end
+
+        private
+
+        # Complex argument sets are not supported in query params (e.g. nested objects)
+        # For any LookupArgumentSet only one argument is expected to be provided.
+        # However, OpenAPI does not currently support describing mutually exclusive query params.
+        # refer to: https://swagger.io/docs/specification/describing-parameters/#dependencies
+        def generate_argument_set_params
+          @argument.type.klass.definition.arguments.each_value do |child_arg|
+            param = {
+              name: "#{@argument.name}[#{child_arg.name}]",
+              in: "query",
+              schema: generate_scalar_schema(child_arg)
+            }
+            description = []
+            description << formatted_description(@argument.description) if @argument.description.present?
+            description << formatted_description(child_arg.description) if child_arg.description.present?
+            description << "All '#{@argument.name}[]' params are mutually exclusive, only one can be provided."
+            param[:description] = description.join(" ")
+            add_to_parameters(param)
+          end
+        end
+
+        def add_to_parameters(param)
+          @route_spec[:parameters] << param
+        end
+
+      end
+    end
+  end
+end

data/lib/apia/open_api/objects/path.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# A Path Object describes a single endpoint in the API
+#
+# "paths": {
+#   "/data_centers/:data_center": {
+#     "get": {
+#       "operationId": "get:data_center",
+#       "tags": ["Core"],
+#       "parameters": [...],
+#       "responses": {...},
+#     }
+#   },
+#   "/virtual_machines/:virtual_machine/start": {
+#     "post": {
+#       "operationId": "post:virtual_machine_start",
+#       "requestBody": {...}
+#       "responses": {
+#         "200": {...}
+#       }
+#     }
+#   }
+# }
+
+module Apia
+  module OpenApi
+    module Objects
+      class Path
+
+        include Apia::OpenApi::Helpers
+
+        def initialize(spec:, path_ids:, route:, name:, api_authenticator:)
+          @spec = spec
+          @path_ids = path_ids
+          @route = route
+          @api_authenticator = api_authenticator
+          @route_spec = {
+            operationId: convert_route_to_id,
+            tags: [name]
+          }
+        end
+
+        def add_to_spec
+          path = @route.path
+          if @route.request_method == :get
+            add_parameters
+          else
+            add_request_body
+          end
+
+          @spec[:paths]["/#{path}"] ||= {}
+          @spec[:paths]["/#{path}"][@route.request_method.to_s] = @route_spec
+
+          add_responses
+        end
+
+        private
+
+        # aka query params
+        def add_parameters
+          @route_spec[:parameters] ||= []
+
+          @route.endpoint.definition.argument_set.definition.arguments.each_value do |arg|
+            Parameters.new(spec: @spec, argument: arg, route_spec: @route_spec).add_to_spec
+          end
+        end
+
+        def add_request_body
+          RequestBody.new(spec: @spec, route: @route, route_spec: @route_spec).add_to_spec
+        end
+
+        def add_responses
+          Response.new(
+            spec: @spec,
+            path_ids: @path_ids,
+            route: @route,
+            route_spec: @route_spec,
+            api_authenticator: @api_authenticator
+          ).add_to_spec
+        end
+
+        # It's worth creating a 'nice' operationId for each route, as this is used as the
+        # basis for the method name when calling the endpoint using a generated client.
+        def convert_route_to_id
+          parts = @route.path.split("/")
+          params = parts.each_with_object([]) do |part, memo|
+            memo << part[1..] if part.start_with?(":")
+          end
+          result_parts = []
+
+          parts.each do |part|
+            if part.start_with?(":")
+              part_without_prefix = part[1..]
+              next if result_parts.include?(part_without_prefix)
+
+              result_parts << part_without_prefix
+            elsif params.none? { |param| part == param || part.match(/#{param.pluralize}/) }
+              result_parts << part
+            end
+          end
+
+          id = "#{@route.request_method}:#{result_parts.join('_')}"
+          if @path_ids.include?(id)
+            id = "#{@route.request_method}:#{@route.path}"
+          end
+          @path_ids << id
+
+          id
+        end
+
+      end
+    end
+  end
+end

data/lib/apia/open_api/objects/request_body.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# A RequestBody Object describes the payload body that can be passed to an endpoint
+# These are declared (if necessary) for any endpoint that is not a GET request.
+#
+# "requestBody": {
+#   "content": {
+#     "application/json": {
+#       "schema": {
+#         "properties": {
+#           "virtual_machine": {
+#             "$ref": "#/components/schemas/CoreAPI_ArgumentSets_VirtualMachineLookup"
+#           }
+#         }
+#       }
+#     }
+#   }
+# }
+module Apia
+  module OpenApi
+    module Objects
+      class RequestBody
+
+        include Apia::OpenApi::Helpers
+
+        def initialize(spec:, route:, route_spec:)
+          @spec = spec
+          @route = route
+          @route_spec = route_spec
+          @properties = {}
+        end
+
+        def add_to_spec
+          required = []
+          @route.endpoint.definition.argument_set.definition.arguments.each_value do |arg|
+            required << arg.name.to_s if arg.required?
+            if arg.array?
+              if arg.type.argument_set? || arg.type.enum?
+                items = generate_schema_ref(arg)
+              else
+                items = generate_scalar_schema(arg)
+              end
+
+              @properties[arg.name.to_s] = {
+                type: "array",
+                items: items
+              }
+            elsif arg.type.argument_set? || arg.type.enum?
+              @properties[arg.name.to_s] = generate_schema_ref(arg)
+            else
+              @properties[arg.name.to_s] = generate_scalar_schema(arg)
+            end
+          end
+
+          schema = { properties: @properties }
+          schema[:required] = required unless required.empty?
+
+          @route_spec[:requestBody] = {
+            content: {
+              "application/json": {
+                schema: schema
+              }
+            }
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/apia/open_api/objects/response.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+# For each endpoint, we need to generate a response schema.
+#
+# "responses": {
+#   "200": {
+#     "description": "Format the given time",
+#     "content": {
+#       "application/json": {
+#         "schema": {
+#           "properties": {
+#             "formatted_time": {
+#               "type": "string"
+#             }
+#           },
+#           "required": [
+#             "formatted_time"
+#           ]
+#         }
+#       }
+#     }
+#   }
+# }
+module Apia
+  module OpenApi
+    module Objects
+      class Response
+
+        include Apia::OpenApi::Helpers
+
+        def initialize(spec:, path_ids:, route:, route_spec:, api_authenticator:)
+          @spec = spec
+          @path_ids = path_ids
+          @route = route
+          @endpoint = route.endpoint
+          @route_spec = route_spec
+          @api_authenticator = api_authenticator
+          @http_status = @endpoint.definition.http_status
+        end
+
+        def add_to_spec
+          add_sucessful_response_schema
+          add_error_response_schemas
+        end
+
+        private
+
+        def add_sucessful_response_schema
+          content_schema = {
+            properties: generate_properties_for_successful_response
+          }
+          required_fields = @endpoint.definition.fields.select { |_, field| field.condition.nil? }
+          content_schema[:required] = required_fields.keys if required_fields.any?
+
+          @route_spec[:responses] = {
+            "#{@http_status}": {
+              description: @endpoint.definition.description || "",
+              content: {
+                "application/json": {
+                  schema: content_schema
+                }
+              }
+            }
+          }
+        end
+
+        def generate_properties_for_successful_response
+          @endpoint.definition.fields.reduce({}) do |props, (name, field)|
+            props.merge(generate_properties_for_field(name, field))
+          end
+        end
+
+        # Response fields can often just point to a ref of a schema. But it's also possible to reference
+        # a return type and not include all fields of that type. If `field.include` is defined, we need
+        # to inspect it to determine which fields are included.
+        def generate_properties_for_field(field_name, field)
+          properties = {}
+          if field.type.polymorph?
+            build_properties_for_polymorph(field_name, field, properties)
+          elsif field.array?
+            build_properties_for_array(field_name, field, properties)
+          elsif field.type.object? || field.type.enum?
+            build_properties_for_object_or_enum(field_name, field, properties)
+          else
+            properties[field_name] = generate_scalar_schema(field)
+          end
+          properties[field_name][:nullable] = true if field.null?
+          properties
+        end
+
+        def build_properties_for_polymorph(field_name, field, properties)
+          if field_includes_all_properties?(field)
+            refs = []
+            field.type.klass.definition.options.map do |_, polymorph_option|
+              refs << generate_schema_ref(polymorph_option)
+            end
+            properties[field_name] = { oneOf: refs }
+          else
+            # We assume the partially selected attributes must be present in all of the polymorph options
+            # and that each option returns the same data type for that attribute.
+            # The same 'allOf workaround' is used here as for objects and enums below.
+            ref = generate_schema_ref(
+              field.type.klass.definition.options.values.first,
+              id: generate_field_id(field_name),
+              endpoint: @endpoint,
+              path: [field]
+            )
+
+            properties[field_name] = { allOf: [ref] }
+          end
+          properties[field_name][:description] = field.description if field.description.present?
+        end
+
+        def build_properties_for_array(field_name, field, properties)
+          if field.type.object? || field.type.enum?
+            if field_includes_all_properties?(field)
+              items = generate_schema_ref(field)
+            else
+              items = generate_schema_ref(
+                field,
+                id: generate_field_id(field_name),
+                endpoint: @endpoint,
+                path: [field]
+              )
+            end
+          else
+            items = { type: convert_type_to_open_api_data_type(field.type) }
+          end
+          return unless items
+
+          properties[field_name] = {
+            type: "array",
+            items: items
+          }
+          properties[field_name][:description] = field.description if field.description.present?
+        end
+
+        # Using allOf is a 'workaround' so that we can include a description for the field
+        # In OpenAPI 3.0 sibling properties are not allowed for $refs (but are allowed in 3.1)
+        # We don't want to put the description on the $ref itself because the description is
+        # specific to the endpoint and not necessarily applicable to all uses of the $ref.
+        def build_properties_for_object_or_enum(field_name, field, properties)
+          properties[field_name] = {}
+          properties[field_name][:description] = field.description if field.description.present?
+          if field_includes_all_properties?(field)
+            ref = generate_schema_ref(field)
+          else
+            ref = generate_schema_ref(
+              field,
+              id: generate_field_id(field_name),
+              endpoint: @endpoint,
+              path: [field]
+            )
+          end
+          properties[field_name][:allOf] = [ref]
+        end
+
+        def field_includes_all_properties?(field)
+          field.include.nil?
+        end
+
+        def generate_field_id(field_name)
+          [
+            @route_spec[:operationId].gsub(":", "_").gsub("/", "_").camelize,
+            @http_status,
+            "Response",
+            field_name.to_s
+          ].flatten.join("_").camelize
+        end
+
+        def add_error_response_schemas
+          grouped_potential_errors = potential_errors.map(&:definition).group_by do |d|
+            d.http_status_code.to_s.to_sym
+          end
+
+          sorted_grouped_potential_errors = grouped_potential_errors.sort_by do |http_status_code, _|
+            http_status_code.to_s.to_i
+          end
+
+          sorted_grouped_potential_errors.each do |http_status_code, potential_errors|
+            add_error_response_schema_for_http_status_code(http_status_code, potential_errors)
+          end
+        end
+
+        def api_authenticator_potential_errors
+          @api_authenticator&.definition&.potential_errors
+        end
+
+        def potential_errors
+          argument_set = @endpoint.definition.argument_set
+          lookup_argument_set_errors = argument_set.collate_objects(Apia::ObjectSet.new).values.map do |o|
+            o.type.klass.definition.try(:potential_errors)
+          end.compact
+
+          [
+            api_authenticator_potential_errors,
+            @route.controller&.definition&.authenticator&.definition&.potential_errors,
+            @endpoint.definition&.authenticator&.definition&.potential_errors,
+            lookup_argument_set_errors,
+            @endpoint.definition.potential_errors
+          ].compact.flatten
+        end
+
+        def add_error_response_schema_for_http_status_code(http_status_code, potential_errors)
+          response_schema = generate_potential_error_ref(http_status_code, potential_errors)
+          @route_spec[:responses].merge!(response_schema)
+        end
+
+        def generate_potential_error_ref(http_status_code, potential_errors)
+          { "#{http_status_code}": generate_ref("responses", http_status_code, potential_errors) }
+        end
+
+        def generate_ref(namespace, http_status_code, definitions)
+          id = generate_id_for_error_ref(http_status_code, definitions)
+          if namespace == "responses"
+            add_to_responses_components(http_status_code, definitions, id)
+          else
+            add_to_schemas_components(definitions.first, id)
+          end
+          { "$ref": "#/components/#{namespace}/#{id}" }
+        end
+
+        def generate_id_for_error_ref(http_status_code, definitions)
+          api_authenticator_error_defs = api_authenticator_potential_errors.map(&:definition).select do |d|
+            d.http_status_code.to_s == http_status_code.to_s
+          end
+          if api_authenticator_error_defs.any? && api_authenticator_error_defs == definitions
+            "APIAuthenticator#{http_status_code}Response"
+          elsif definitions.length == 1
+            "#{generate_id_from_definition(definitions.first)}Response"
+          else
+            [
+              (definitions - api_authenticator_error_defs).map do |d|
+                generate_id_from_definition(d)
+              end.join,
+              http_status_code,
+              "Response"
+            ].flatten.join("_").camelize
+          end
+        end
+
+        def add_to_responses_components(http_status_code, definitions, id)
+          return unless @spec.dig(:components, :components, id).nil?
+
+          component_schema = {
+            description: "#{http_status_code} error response"
+          }
+
+          if definitions.length == 1
+            definition = definitions.first
+            component_schema[:description] = definition.description if definition.description.present?
+            schema = generate_schema_properties_for_definition(definition)
+          else # the same http status code is used for multiple errors
+            one_of_id = "OneOf#{id}"
+            @spec[:components][:schemas][one_of_id] = {
+              oneOf: definitions.map { |d| generate_ref("schemas", http_status_code, [d]) }
+            }
+
+            schema = { "$ref": "#/components/schemas/#{one_of_id}" }
+          end
+
+          component_schema[:content] = {
+            "application/json": {
+              schema: schema
+            }
+          }
+          @spec[:components][:responses] ||= {}
+          @spec[:components][:responses][id] = component_schema
+          component_schema
+        end
+
+        def generate_schema_properties_for_definition(definition)
+          detail = generate_schema_ref(definition, id: generate_id_from_definition(definition))
+          {
+            properties: {
+              code: {
+                type: "string",
+                enum: [definition.code]
+              },
+              description: { type: "string" },
+              detail: detail
+            }
+          }
+        end
+
+        def add_to_schemas_components(definition, id)
+          @spec[:components][:schemas] ||= {}
+          component_schema = {
+            type: "object"
+          }
+          component_schema[:description] = definition.description if definition.description.present?
+          component_schema.merge!(generate_schema_properties_for_definition(definition))
+          @spec[:components][:schemas][id] = component_schema
+          component_schema
+        end
+
+      end
+    end
+  end
+end

data/lib/apia/open_api/objects/schema.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Schema Objects loosley map to the re-usable parts of an Apia API, such as:
+# ArgumentSet, Object, Enum, Polymorph
+#
+# "PaginationObject": {
+#   "type": "object",
+#   "properties": {
+#     "current_page": {
+#       "type": "integer"
+#     },
+#     "total_pages": {
+#       "type": "integer"
+#     },
+#     "total": {
+#       "type": "integer"
+#     },
+#     "per_page": {
+#       "type": "integer"
+#     },
+#   }
+# }
+#
+# We generate Schema Objects for two reasons:
+# 1. They are added to the components section of the spec, so they can be referenced and re-used from elsewhere.
+# e.g. the pagination object example above would be referenced from endpoint responses as:
+# { "$ref": "#/components/schemas/PaginationObject" }
+#
+# 2. When the response does not include all fields from an existing Objects::Schema, we cannot use a $ref.
+# So we generate a new Objects::Schema and include it 'inline' for that specific endpoint.
+module Apia
+  module OpenApi
+    module Objects
+      class Schema
+
+        include Apia::OpenApi::Helpers
+
+        def initialize(spec:, definition:, schema:, id:, endpoint: nil, path: nil)
+          @spec = spec
+          @definition = definition
+          @schema = schema
+          @id = id
+          @endpoint = endpoint
+          @path = path
+          @children = []
+        end
+
+        def add_to_spec
+          if @definition.try(:type)&.polymorph?
+            build_schema_for_polymorph
+            return @schema
+          end
+
+          generate_child_schemas
+          @schema
+        end
+
+        private
+
+        def build_schema_for_polymorph
+          @schema[:type] = "object"
+          @schema[:properties] ||= {}
+          refs = []
+          @definition.type.klass.definition.options.map do |_, polymorph_option|
+            refs << generate_schema_ref(polymorph_option)
+          end
+          @schema[:properties][@definition.name.to_s] = { oneOf: refs }
+        end
+
+        def error_definition?
+          @definition.is_a?(Apia::Definitions::Error)
+        end
+
+        def enum_definition?
+          @definition.try(:type)&.enum?
+        end
+
+        def generate_child_schemas
+          if error_definition?
+            @children = @definition.fields.values
+          elsif @definition.type.argument_set?
+            @children = @definition.type.klass.definition.arguments.values
+            @schema[:description] ||=
+              "All '#{@definition.name}[]' params are mutually exclusive, only one can be provided."
+          elsif @definition.type.object?
+            @children = @definition.type.klass.definition.fields.values
+          elsif enum_definition?
+            @children = @definition.type.klass.definition.values.values
+          end
+
+          return if @children.empty?
+
+          all_properties_included = error_definition? || enum_definition? || @endpoint.nil?
+          @children.each do |child|
+            next unless @endpoint.nil? || (!enum_definition? && @endpoint.include_field?(@path + [child]))
+
+            if child.respond_to?(:array?) && child.array?
+              generate_schema_for_child_array(@schema, child, all_properties_included)
+            else
+              generate_schema_for_child(@schema, child, all_properties_included)
+            end
+          end
+        end
+
+        def generate_schema_for_child_array(schema, child, all_properties_included)
+          child_schema = generate_schema_for_child({}, child, all_properties_included)
+          items = child_schema.dig(:properties, child.name.to_s)
+          return unless items.present?
+
+          schema[:properties] ||= {}
+          schema[:properties][child.name.to_s] = {
+            type: "array",
+            items: items
+          }
+        end
+
+        def generate_schema_for_child(schema, child, all_properties_included)
+          if enum_definition?
+            schema[:type] = "string"
+            schema[:enum] = @children.map { |c| c[:name] }
+          elsif child.type.argument_set? || child.type.enum? || child.type.polymorph?
+            schema[:type] = "object"
+            schema[:properties] ||= {}
+            schema[:properties][child.name.to_s] = generate_schema_ref(child)
+          elsif child.type.object?
+            generate_properties_for_object(schema, child, all_properties_included)
+          else # scalar
+            schema[:type] = "object"
+            schema[:properties] ||= {}
+            schema[:properties][child.name.to_s] = generate_scalar_schema(child)
+          end
+
+          if child.try(:required?)
+            schema[:required] ||= []
+            schema[:required] << child.name.to_s
+          end
+          schema
+        end
+
+        def generate_properties_for_object(schema, child, all_properties_included)
+          schema[:type] = "object"
+          schema[:properties] ||= {}
+          if all_properties_included
+            schema[:properties][child.name.to_s] = generate_schema_ref(child)
+          else
+            child_path = @path.nil? ? nil : @path + [child]
+            schema[:properties][child.name.to_s] = generate_schema_ref(
+              child,
+              id: "#{@id}_#{child.name}".camelize,
+              endpoint: @endpoint,
+              path: child_path
+            )
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/apia/open_api/objects.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+Dir.glob(File.join(File.dirname(__FILE__), "objects", "*.rb")).sort.each do |file|
+  require_relative file
+end
+
+module Apia
+  module OpenApi
+    module Objects
+    end
+  end
+end

data/lib/apia/open_api/rack.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Apia
+  module OpenApi
+    class Rack
+
+      def initialize(app, api_class:, schema_path:, **options)
+        @app = app
+        @api_class = api_class
+        @schema_path = "/#{schema_path.sub(/\A\/+/, '').sub(/\/+\z/, '')}"
+        @options = options
+      end
+
+      def development?
+        env_is_dev = ENV["RACK_ENV"] == "development"
+        return true if env_is_dev && @options[:development].nil?
+
+        @options[:development] == true
+      end
+
+      def api_class
+        return Object.const_get(@api_class) if @api_class.is_a?(String) && development?
+        return @cached_api ||= Object.const_get(@api_class) if @api_class.is_a?(String)
+
+        @api_class
+      end
+
+      def base_url
+        @options[:base_url] || "https://api.example.com/api/v1"
+      end
+
+      def call(env)
+        if @options[:hosts]&.none? { |host| host == env["HTTP_HOST"] }
+          return @app.call(env)
+        end
+
+        unless env["PATH_INFO"] == @schema_path
+          return @app.call(env)
+        end
+
+        specification = Specification.new(api_class, base_url, @options[:name])
+        body = specification.json
+
+        [200, { "Content-Type" => "application/json", "Content-Length" => body.bytesize.to_s }, [body]]
+      end
+
+    end
+  end
+end

data/lib/apia/open_api/specification.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/inflector"
+require "active_support/core_ext"
+require_relative "helpers"
+require_relative "objects"
+
+module Apia
+  module OpenApi
+    class Specification
+
+      include Apia::OpenApi::Helpers
+
+      OPEN_API_VERSION = "3.0.0" # The Ruby client generator currently only supports v3.0.0 https://openapi-generator.tech/
+
+      def initialize(api, base_url, name)
+        @api = api
+        @base_url = base_url
+        @name = name || "Core" # will be suffixed with 'Api' and used in the client generator
+        @spec = {
+          openapi: OPEN_API_VERSION,
+          info: {},
+          servers: [],
+          paths: {},
+          components: {
+            schemas: {}
+          },
+          security: []
+        }
+        @path_ids = []
+        build_spec
+      end
+
+      def json
+        JSON.pretty_generate(@spec)
+      end
+
+      private
+
+      def build_spec
+        add_info
+        add_servers
+        add_paths
+        add_security
+      end
+
+      def add_info
+        title = @api.definition.name || @api.definition.id
+        @spec[:info] = {
+          version: "1.0.0",
+          title: title
+        }
+        @spec[:info][:description] = @api.definition.description || "Welcome to the documentation for the #{title}"
+      end
+
+      def add_servers
+        @spec[:servers] << { url: @base_url }
+      end
+
+      def add_paths
+        @api.definition.route_set.routes.each do |route|
+          next unless route.endpoint.definition.schema? # not all routes should be documented
+
+          Objects::Path.new(
+            spec: @spec,
+            path_ids: @path_ids,
+            route: route,
+            name: @name,
+            api_authenticator: @api.definition.authenticator
+          ).add_to_spec
+        end
+      end
+
+      def add_security
+        @api.objects.select { |o| o.ancestors.include?(Apia::Authenticator) }.each do |authenticator|
+          next unless authenticator.definition.type == :bearer
+
+          Objects::BearerSecurityScheme.new(spec: @spec, authenticator: authenticator).add_to_spec
+        end
+      end
+
+    end
+  end
+end

data/lib/apia/open_api/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Apia
+  module OpenApi
+
+    VERSION = "0.1.0"
+
+  end
+end

data/lib/apia/open_api.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "open_api/version"
+require_relative "open_api/rack"
+require_relative "open_api/specification"

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: apia-open_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Sturgess
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-12-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- apia-open_api.gemspec
+- lib/apia/open_api.rb
+- lib/apia/open_api/helpers.rb
+- lib/apia/open_api/objects.rb
+- lib/apia/open_api/objects/bearer_security_scheme.rb
+- lib/apia/open_api/objects/parameters.rb
+- lib/apia/open_api/objects/path.rb
+- lib/apia/open_api/objects/request_body.rb
+- lib/apia/open_api/objects/response.rb
+- lib/apia/open_api/objects/schema.rb
+- lib/apia/open_api/rack.rb
+- lib/apia/open_api/specification.rb
+- lib/apia/open_api/version.rb
+homepage: https://github.com/krystal/apia-openapi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/krystal/apia-openapi
+  source_code_uri: https://github.com/krystal/apia-openapi
+  changelog_uri: https://github.com/krystal/apia-openapi/changelog.md
+  rubygems_mfa_required: 'false'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Apia OpenAPI spec generator
+test_files: []