rspec-openapi 0.1.0 → 0.18.4

data/README.md

@@ -1,6 +1,6 @@
-# rspec-openapi
+# rspec-openapi [![Gem Version](https://badge.fury.io/rb/rspec-openapi.svg)](https://rubygems.org/gems/rspec-openapi) [![test](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml/badge.svg)](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/exoego/rspec-openapi/branch/master/graph/badge.svg?token=egYm6AlxkD)](https://codecov.io/gh/exoego/rspec-openapi) [![Ruby-toolbox](https://img.shields.io/badge/ruby-toolbox-a61414?cacheSeconds=31536000)](https://www.ruby-toolbox.com/projects/rspec-openapi)
 
-Generate OpenAPI specs from RSpec request specs.
+Generate OpenAPI schema from RSpec request specs.
 
 ## What's this?
 
@@ -24,12 +24,12 @@ gem 'rspec-openapi', group: :test
 Run rspec with OPENAPI=1 to generate `doc/openapi.yaml` for your request specs.
 
 ```bash
-$ OPENAPI=1 rspec
+$ OPENAPI=1 bundle exec rspec
 ```
 
 ### Example
 
-Let's say you have [a request spec](./spec/requests/table_spec.rb) like this:
+Let's say you have [a request spec](https://github.com/exoego/rspec-openapi/blob/24e5c567c2e90945c7a41f19f71634ac028cc314/spec/requests/rails_spec.rb#L38) like this:
 
 ```rb
 RSpec.describe 'Tables', type: :request do
@@ -52,10 +52,10 @@ end
 If you run the spec with `OPENAPI=1`,
 
 ```
-OPENAPI=1 be rspec spec/requests/tables_spec.rb
+OPENAPI=1 rspec spec/requests/tables_spec.rb
 ```
 
-It will generate [`doc/openapi.yaml` file](./spec/railsapp/doc/openapi.yaml) like:
+It will generate [`doc/openapi.yaml` file](./spec/rails/doc/openapi.yaml) like:
 
 ```yml
 openapi: 3.0.3
@@ -64,16 +64,20 @@ info:
 paths:
   "/tables":
     get:
-      summary: tables#index
+      summary: index
+      tags:
+      - Table
       parameters:
       - name: page
         in: query
         schema:
           type: integer
+        example: 1
       - name: per
         in: query
         schema:
           type: integer
+        example: 10
       responses:
         '200':
           description: returns a list of tables
@@ -93,20 +97,226 @@ paths:
 
 and the schema file can be used as an input of [Swagger UI](https://github.com/swagger-api/swagger-ui) or [Redoc](https://github.com/Redocly/redoc).
 
-![Redoc example](./spec/railsapp/doc/screenshot.png)
+![Redoc example](./spec/apps/rails/doc/screenshot.png)
 
 
 ### Configuration
 
-If you want to change the path to generate a spec from `doc/openapi.yaml`, use:
+The following configurations are optional.
 
 ```rb
+require 'rspec/openapi'
+
+# Change the path to generate schema from `doc/openapi.yaml`
 RSpec::OpenAPI.path = 'doc/schema.yaml'
+
+# Change the output type to JSON
+RSpec::OpenAPI.path = 'doc/schema.json'
+
+# Or generate multiple partial schema files, given an RSpec example
+RSpec::OpenAPI.path = -> (example) {
+  case example.file_path
+  when %r[spec/requests/api/v1/] then 'doc/openapi/v1.yaml'
+  when %r[spec/requests/api/v2/] then 'doc/openapi/v2.yaml'
+  else 'doc/openapi.yaml'
+  end
+}
+
+# Change the default title of the generated schema
+RSpec::OpenAPI.title = 'OpenAPI Documentation'
+
+# Or generate individual titles for your partial schema files, given an RSpec example
+RSpec::OpenAPI.title = -> (example) {
+  case example.file_path
+  when %r[spec/requests/api/v1/] then 'API v1 Documentation'
+  when %r[spec/requests/api/v2/] then 'API v2 Documentation'
+  else 'OpenAPI Documentation'
+  end
+}
+
+# Disable generating `example`
+RSpec::OpenAPI.enable_example = false
+
+# Change `info.version`
+RSpec::OpenAPI.application_version = '1.0.0'
+
+# Set the info header details
+RSpec::OpenAPI.info = {
+  description: 'My beautiful API',
+  license: {
+    'name': 'Apache 2.0',
+    'url': 'https://www.apache.org/licenses/LICENSE-2.0.html'
+  }
+}
+
+# Set request `headers` - generate parameters with headers for a request
+RSpec::OpenAPI.request_headers = %w[X-Authorization-Token]
+
+# Set response `headers` - generate parameters with headers for a response
+RSpec::OpenAPI.response_headers = %w[X-Cursor]
+
+# Set `servers` - generate servers of a schema file
+RSpec::OpenAPI.servers = [{ url: 'http://localhost:3000' }]
+
+# Set `security_schemes` - generate security schemes
+RSpec::OpenAPI.security_schemes = {
+  'MyToken' => {
+    description: 'Authenticate API requests via a JWT',
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+  },
+}
+
+# Generate a comment on top of a schema file
+RSpec::OpenAPI.comment = <<~EOS
+  This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi
+
+  When you write a spec in spec/requests, running the spec with `OPENAPI=1 rspec` will
+  update this file automatically. You can also manually edit this file.
+EOS
+
+# Generate a custom description, given an RSpec example
+RSpec::OpenAPI.description_builder = -> (example) { example.description }
+
+# Generate a custom summary, given an RSpec example
+# This example uses the summary from the example_group.
+RSpec::OpenAPI.summary_builder = ->(example) { example.metadata.dig(:example_group, :openapi, :summary) }
+
+# Generate a custom tags, given an RSpec example
+# This example uses the tags from the parent_example_group
+RSpec::OpenAPI.tags_builder = -> (example) { example.metadata.dig(:example_group, :parent_example_group, :openapi, :tags) }
+
+# Change the example type(s) that will generate schema
+RSpec::OpenAPI.example_types = %i[request]
+
+# Configure which path params to ignore
+# :controller and :action always exist. :format is added when routes is configured as such.
+RSpec::OpenAPI.ignored_path_params = %i[controller action format]
+
+# Configure which paths to ignore.
+# You can exclude some specs via `openapi: false`.
+# But, in a complex API usage scenario, you may need to include spec itself, but exclude some private paths.
+# In that case, you can specify the paths to ignore.
+# String or Regexp is acceptable.
+RSpec::OpenAPI.ignored_paths = ["/admin/full/path/", Regexp.new("^/_internal/")]
+
+# Your custom post-processing hook (like unrandomizing IDs)
+RSpec::OpenAPI.post_process_hook = -> (path, records, spec) do
+  RSpec::OpenAPI::HashHelper.matched_paths(spec, 'paths.*.*.responses.*.content.*.*.*.id').each do |paths|
+    spec.dig(*paths[0..-2]).merge!(id: '123')
+  end
+end
+```
+
+### Can I use rspec-openapi with `$ref` to minimize duplication of schema?
+
+Yes, rspec-openapi v0.7.0+ supports [`$ref` mechanism](https://swagger.io/docs/specification/using-ref/) and generates
+schemas under `#/components/schemas` with some manual steps.
+
+1. First, generate plain OpenAPI file.
+2. Then, manually replace the duplications with `$ref`.
+
+```yaml
+paths:
+  "/users":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/User"
+  "/users/{id}":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+# Note) #/components/schemas is not needed to be defined.
+```
+
+3. Then, re-run rspec-openapi. It will generate `#/components/schemas` with the referenced schema (`User` for example) newly-generated or updated.
+
+```yaml
+paths:
+  "/users":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/User"
+  "/users/{id}":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        role:
+          type: array
+          items:
+            type: string
+```
+
+rspec-openapi also supports `$ref` in `properties` of schemas. Example)
+
+```yaml
+paths:
+  "/locations":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Location"
+components:
+  schemas:
+    Location:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        Coordinate:
+          "$ref": "#/components/schemas/Coordinate"
+    Coordinate:
+      type: object
+      properties:
+        lat:
+          type: string
+        lon:
+          type: string
 ```
 
+Note that automatic `schemas` update feature is still new and may not work in complex scenario.
+If you find a room for improvement, open an issue.
+
 ### How can I add information which can't be generated from RSpec?
 
-rspec-openapi tries to keep manual modifications as much as possible when generating specs.
+rspec-openapi tries to preserve manual modifications as much as possible when generating specs.
 You can directly edit `doc/openapi.yaml` as you like without spoiling the automatic generation capability.
 
 ### Can I exclude specific specs from OpenAPI generation?
@@ -127,28 +337,57 @@ RSpec.describe '/resources', type: :request do
 end
 ```
 
-## Project status
+## Customizations
 
-PoC / Experimental
+Some examples' attributes can be overwritten via RSpec metadata options. Example:
 
-This worked for some of my Rails apps, but this may raise a basic error for your app.
+```rb
+  describe 'GET /api/v1/posts', openapi: {
+    summary: 'list all posts',
+    description: 'list all posts ordered by pub_date',
+    tags: %w[v1 posts],
+    required_request_params: %w[limit],
+    security: [{"MyToken" => []}],
+  } do
+    # ...
+  end
+```
+
+**NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
+
+## Experimental minitest support
+
+Even if you are not using `rspec` this gem might help you with its experimental support for `minitest`.
+
+Example:
+
+```rb
+class TablesTest < ActionDispatch::IntegrationTest
+  openapi!
 
-### Current limitations
+  test "GET /index returns a list of tables" do
+    get '/tables', params: { page: '1', per: '10' }, headers: { authorization: 'k0kubun' }
+    assert_response :success
+  end
+
+  test "GET /index does not return tables if unauthorized" do
+    get '/tables'
+    assert_response :unauthorized
+  end
+
+  # ...
+end
+```
+
+It should work with both classes inheriting from `ActionDispatch::IntegrationTest` and with classes using `Rack::Test` directly, as long as you call `openapi!` in your test class.
 
-* Generating a JSON file is not supported yet
-* This only works for RSpec request specs
-* Only Rails is supported for looking up a request route
+Please note that not all features present in the rspec integration work with minitest (yet). For example, custom per test case metadata is not supported. A custom `description_builder` will not work either.
 
-### Other missing features with notes
+Run minitest with OPENAPI=1 to generate `doc/openapi.yaml` for your request specs.
 
-* Delete obsoleted endpoints
-  * Give up, or at least make the feature optional?
-  * Running all to detect obsoleted endpoints is sometimes not realistic anyway.
-* Intelligent merges
-  * To maintain both automated changes and manual edits, the schema merge needs to be intelligent.
-  * We'll just deep-reverse-merge schema for now, but if there's a $ref for example, modifications
-    there should be rerouted to the referenced object.
-  * A type could be an array of all possible types when merged.
+```bash
+$ OPENAPI=1 bundle exec rails t
+```
 
 ## Links
 
@@ -160,9 +399,9 @@ Existing RSpec plugins which have OpenAPI integration:
 
 ## Acknowledgements
 
-This gem was heavily inspired by the following gem:
+* Heavily inspired by [r7kamura/autodoc](https://github.com/r7kamura/autodoc)
+* Orignally created by [k0kubun](https://github.com/k0kubun) and the ownership was transferred to [exoego](https://github.com/exoego) in 2022-11-29.
 
-* [r7kamura/autodoc](https://github.com/r7kamura/autodoc)
 
 ## License
 

data/Rakefile

@@ -1,6 +1,10 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
 
-RSpec::Core::RakeTask.new(:spec)
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-task :default => :spec
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = 'spec/rspec/openapi/**/*_spec.rb'
+end
+
+task default: :spec

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "rspec/openapi"
+require 'bundler/setup'
+require 'rspec/openapi'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "rspec/openapi"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/lib/rspec/openapi/components_updater.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'hash_helper'
+
+class << RSpec::OpenAPI::ComponentsUpdater = Object.new
+  # @param [Hash] base
+  # @param [Hash] fresh
+  def update!(base, fresh)
+    # Top-level schema: Used as the body of request or response
+    top_level_refs = paths_to_top_level_refs(base)
+    return if top_level_refs.empty?
+
+    fresh_schemas = build_fresh_schemas(top_level_refs, base, fresh)
+
+    # Nested schema: References in Top-level schemas. May contain some top-level schema.
+    generated_schema_names = fresh_schemas.keys
+    nested_refs = find_non_top_level_nested_refs(base, generated_schema_names)
+    nested_refs.each do |paths|
+      # Slice between the parent name and the element before "$ref"
+      # ["components", "schema", "Table", "properties", "database",                       "$ref"]
+      #  0             1         2 ^....................^
+      # ["components", "schema", "Table", "properties", "columns", "items",               "$ref"]
+      #  0             1         2 ^...............................^
+      # ["components", "schema", "Table", "properties", "owner", "properties", "company", "$ref"]
+      #  0             1         2 ^...........................................^
+      needle = paths.reject { |path| path.is_a?(Integer) || path == :oneOf }
+      needle = needle.slice(2, needle.size - 3)
+      nested_schema = fresh_schemas.dig(*needle)
+
+      # Skip if the property using $ref is not found in the parent schema. The property may be removed.
+      next if nested_schema.nil?
+
+      schema_name = base.dig(*paths)&.gsub('#/components/schemas/', '')&.to_sym
+      fresh_schemas[schema_name] ||= {}
+      RSpec::OpenAPI::SchemaMerger.merge!(fresh_schemas[schema_name], nested_schema)
+    end
+
+    RSpec::OpenAPI::SchemaMerger.merge!(base, { components: { schemas: fresh_schemas } })
+    RSpec::OpenAPI::SchemaCleaner.cleanup_components_schemas!(base, { components: { schemas: fresh_schemas } })
+  end
+
+  private
+
+  def build_fresh_schemas(references, base, fresh)
+    references.inject({}) do |acc, paths|
+      ref_link = dig_schema(base, paths)[:$ref]
+      schema_name = ref_link.to_s.gsub('#/components/schemas/', '')
+      schema_body = dig_schema(fresh, paths.reject { |path| path.is_a?(Integer) })
+
+      RSpec::OpenAPI::SchemaMerger.merge!(acc, { schema_name => schema_body })
+    end
+  end
+
+  def dig_schema(obj, paths)
+    # Response code can be an integer
+    paths = paths.map { |path| path.is_a?(Integer) ? path : path.to_sym }
+    item_schema = obj.dig(*paths, :schema, :items)
+    object_schema = obj.dig(*paths, :schema)
+    one_of_schema = obj.dig(*paths.take(paths.size - 1), :schema, :oneOf, paths.last)
+
+    item_schema || object_schema || one_of_schema
+  end
+
+  def paths_to_top_level_refs(base)
+    request_bodies = RSpec::OpenAPI::HashHelper.matched_paths(base, 'paths.*.*.requestBody.content.application/json')
+    responses = RSpec::OpenAPI::HashHelper.matched_paths(base, 'paths.*.*.responses.*.content.application/json')
+    (request_bodies + responses).flat_map do |paths|
+      object_paths = find_object_refs(base, paths)
+      one_of_paths = find_one_of_refs(base, paths)
+
+      object_paths || one_of_paths || []
+    end
+  end
+
+  def find_non_top_level_nested_refs(base, generated_names)
+    nested_refs = [
+      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties.*.$ref'),
+      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties.*.items.$ref'),
+      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'oneOf.*.$ref'),
+    ]
+    # Reject already-generated schemas to reduce unnecessary loop
+    nested_refs.reject do |paths|
+      ref_link = base.dig(*paths)
+      schema_name = ref_link.gsub('#/components/schemas/', '')
+      generated_names.include?(schema_name)
+    end
+  end
+
+  def find_one_of_refs(base, paths)
+    dig_schema(base, paths)&.dig(:oneOf)&.map&.with_index do |schema, index|
+      paths + [index] if schema&.dig(:$ref)&.start_with?('#/components/schemas/')
+    end&.compact
+  end
+
+  def find_object_refs(base, paths)
+    [paths] if dig_schema(base, paths)&.dig(:$ref)&.start_with?('#/components/schemas/')
+  end
+end

data/lib/rspec/openapi/default_schema.rb

@@ -1,11 +1,23 @@
+# frozen_string_literal: true
+
 class << RSpec::OpenAPI::DefaultSchema = Object.new
   def build(title)
-    {
+    spec = {
       openapi: '3.0.3',
       info: {
         title: title,
+        version: RSpec::OpenAPI.application_version,
       },
+      servers: RSpec::OpenAPI.servers,
       paths: {},
-    }.freeze
+    }
+
+    if RSpec::OpenAPI.security_schemes.present?
+      spec[:components] = {
+        securitySchemes: RSpec::OpenAPI.security_schemes,
+      }
+    end
+
+    spec.freeze
   end
 end

data/lib/rspec/openapi/extractors/hanami.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'dry/inflector'
+require 'hanami'
+
+# https://github.com/hanami/router/blob/97f75b8529574bd4ff23165460e82a6587bc323c/lib/hanami/router/inspector.rb#L13
+class Inspector
+  attr_accessor :routes, :inflector
+
+  def initialize(routes: [])
+    @routes = routes
+    @inflector = Dry::Inflector.new
+  end
+
+  def add_route(route)
+    routes.push(route)
+  end
+
+  def call(verb, path)
+    route = routes.find { |r| r.http_method == verb && r.path == path }
+
+    if route.to.is_a?(Proc)
+      {
+        tags: [],
+        summary: "#{verb} #{path}",
+      }
+    else
+      data = route.to.split('.')
+
+      {
+        tags: [inflector.classify(data[0])],
+        summary: data[1],
+      }
+    end
+  end
+end
+
+InspectorAnalyzer = Inspector.new
+
+# Add default parameter to load inspector before test cases run
+module InspectorAnalyzerPrepender
+  def router(inspector: InspectorAnalyzer)
+    super
+  end
+end
+
+Hanami::Slice::ClassMethods.prepend(InspectorAnalyzerPrepender)
+
+# Extractor for hanami
+class << RSpec::OpenAPI::Extractors::Hanami = Object.new
+  # @param [ActionDispatch::Request] request
+  # @param [RSpec::Core::Example] example
+  # @return Array
+  def request_attributes(request, example)
+    route = Hanami.app.router.recognize(Rack::MockRequest.env_for(request.path, method: request.method))
+
+    return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless route.routable?
+
+    metadata = example.metadata[:openapi] || {}
+    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
+    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    operation_id = metadata[:operation_id]
+    required_request_params = metadata[:required_request_params] || []
+    security = metadata[:security]
+    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
+    deprecated = metadata[:deprecated]
+    path = request.path
+
+    raw_path_params = route.params
+
+    result = InspectorAnalyzer.call(request.method, add_id(path, route))
+
+    summary ||= result[:summary]
+    tags ||= result[:tags]
+    path = add_openapi_id(path, route)
+
+    raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
+
+    [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated]
+  end
+
+  # @param [RSpec::ExampleGroups::*] context
+  def request_response(context)
+    request = ActionDispatch::Request.new(context.last_request.env)
+    request.body.rewind if request.body.respond_to?(:rewind)
+    response = ActionDispatch::TestResponse.new(*context.last_response.to_a)
+
+    [request, response]
+  end
+
+  def add_id(path, route)
+    return path if route.params.empty?
+
+    route.params.each_pair do |key, value|
+      path = path.sub("/#{value}", "/:#{key}")
+    end
+
+    path
+  end
+
+  def add_openapi_id(path, route)
+    return path if route.params.empty?
+
+    route.params.each_pair do |key, value|
+      path = path.sub("/#{value}", "/{#{key}}")
+    end
+
+    path
+  end
+end

data/lib/rspec/openapi/extractors/rack.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Extractor for rack
+class << RSpec::OpenAPI::Extractors::Rack = Object.new
+  # @param [ActionDispatch::Request] request
+  # @param [RSpec::Core::Example] example
+  # @return Array
+  def request_attributes(request, example)
+    metadata = example.metadata[:openapi] || {}
+    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
+    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    operation_id = metadata[:operation_id]
+    required_request_params = metadata[:required_request_params] || []
+    security = metadata[:security]
+    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
+    deprecated = metadata[:deprecated]
+    raw_path_params = request.path_parameters
+    path = request.path
+    summary ||= "#{request.method} #{path}"
+    [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated]
+  end
+
+  # @param [RSpec::ExampleGroups::*] context
+  def request_response(context)
+    request = ActionDispatch::Request.new(context.last_request.env)
+    request.body.rewind if request.body.respond_to?(:rewind)
+    response = ActionDispatch::TestResponse.new(*context.last_response.to_a)
+
+    [request, response]
+  end
+end