rspec-openapi 0.1.5 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adaf5569dc17aa32bf1f570f77023097aed29ce2b76ee9c9c62ab5b48208dc31
-  data.tar.gz: ddf2e7c33c5a02a86f610dc68d6e3a46f1be0a44b2df838ab1681c9e09cca5dc
+  metadata.gz: 98be98f98f98819f1d1b018ad1a155184ebbe1c226b96414895acc0f60106b18
+  data.tar.gz: 6985138afe53b9223647f67d8802acdab580d737c18caec6b312d625d649d7c7
 SHA512:
-  metadata.gz: 07011c0a01fce891827ee62898a814ce653f17b68a13dca3dd11c4b166e3ef0c864675a43a86c8f94175ea50936d0cfb3a3a386c2c1eeaf68c13f3c180731be2
-  data.tar.gz: cb24d803cc198dd7df3578147a54c4160dbd160bb642e5ecfad149c5c119a3d6cd35a2fba02618b7c58a2511b5907129ced6d408fbe2e341cd616d0224f01a4d
+  metadata.gz: 13906efcf4d94054aea6c6132c09990bc99f264fc3fc37842f6d4d98515a5974f91a39cc3c7d749f0b2f24107e7fc9fb6bb94cfa6f3655fa0f13429101d17a20
+  data.tar.gz: 10ca07bb2370cf61dee4bdbc0d19d1194d64daf558813d8fff113868226a5d1ff6036f71071f58106492592e012ab999dc430976e1e5b7a4361dc36ec1bc5fb8

data/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: test
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container: ${{ matrix.ruby }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - ruby:2.5
+          - ruby:2.6
+          - ruby:2.7
+    steps:
+      - uses: actions/checkout@v2
+      - name: bundle install
+        run: bundle install -j$(nproc) --retry 3
+      - run: bundle exec rspec
+        timeout-minutes: 1

data/.rspec

@@ -1,3 +1,4 @@
+--exclude-pattern spec/requests/**/*_spec.rb
 --format documentation
+--require rspec/openapi
 --color
---require spec_helper

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## Unreleased
+
+* Add `RSpec::OpenAPI.description_builder` config to dynamically generate a description [experimental]
+  [#6](https://github.com/k0kubun/rspec-openapi/issues/6)
+
+## v0.3.0
+
+* Initial support of rack-test and non-Rails apps [#5](https://github.com/k0kubun/rspec-openapi/issues/5)
+
+## v0.2.2
+
+* Allow disabling `example` by `RSpec::OpenAPI.enable_example = false`
+
+## v0.2.1
+
+* Generate `example` of request body and path / query params
+  [#4](https://github.com/k0kubun/rspec-openapi/issues/4)
+* Remove a wrapper param created by Rails in request body
+  [#4](https://github.com/k0kubun/rspec-openapi/issues/4)
+
+## v0.2.0
+
+* Generate `example` of response body [#3](https://github.com/k0kubun/rspec-openapi/issues/3)
+
 ## v0.1.5
 
 * Support detecting `float` type [#2](https://github.com/k0kubun/rspec-openapi/issues/2)

data/Gemfile

@@ -4,5 +4,9 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rails', '6.0.3.2'
+gem 'roda'
 gem 'rspec-rails'
-gem 'pry'
+
+group :development do
+  gem 'pry'
+end

data/README.md

@@ -1,6 +1,6 @@
-# rspec-openapi
+# rspec-openapi ![test](https://github.com/k0kubun/rspec-openapi/workflows/test/badge.svg)
 
-Generate OpenAPI specs from RSpec request specs.
+Generate OpenAPI schema from RSpec request specs.
 
 ## What's this?
 
@@ -29,7 +29,7 @@ $ OPENAPI=1 rspec
 
 ### Example
 
-Let's say you have [a request spec](./spec/requests/tables_spec.rb) like this:
+Let's say you have [a request spec](./spec/requests/rails/tables_spec.rb) like this:
 
 ```rb
 RSpec.describe 'Tables', type: :request do
@@ -55,7 +55,7 @@ If you run the spec with `OPENAPI=1`,
 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
@@ -93,7 +93,7 @@ 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/rails/doc/screenshot.png)
 
 
 ### Configuration
@@ -104,6 +104,9 @@ The following configurations are optional.
 # Change the path to generate schema from `doc/openapi.yaml`
 RSpec::OpenAPI.path = 'doc/schema.yaml'
 
+# Disable generating `example`
+RSpec::OpenAPI.enable_example = false
+
 # 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
@@ -111,6 +114,9 @@ RSpec::OpenAPI.comment = <<~EOS
   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 a RSpec example
+RSpec::OpenAPI.description_builder = -> (example) { example.description }
 ```
 
 ### How can I add information which can't be generated from RSpec?
@@ -138,15 +144,13 @@ end
 
 ## Project status
 
-PoC / Experimental
+Beta
 
-This worked for some of my Rails apps, but this may raise a basic error for your app.
+Basic features are there, and some people are already using this.
 
-### Current limitations
+### Current limitation
 
 * 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
 
 ### Other missing features with notes
 

data/Rakefile

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

data/lib/rspec/openapi.rb

@@ -3,8 +3,11 @@ require 'rspec/openapi/hooks' if ENV['OPENAPI']
 
 module RSpec::OpenAPI
   @path = 'doc/openapi.yaml'
+  @comment = nil
+  @enable_example = true
+  @description_builder = -> (example) { example.description }
 
   class << self
-    attr_accessor :path, :comment
+    attr_accessor :path, :comment, :enable_example, :description_builder
   end
 end

data/lib/rspec/openapi/hooks.rb

@@ -8,8 +8,9 @@ require 'rspec/openapi/schema_merger'
 records = []
 
 RSpec.configuration.after(:each) do |example|
-  if example.metadata[:type] == :request && example.metadata[:openapi] != false && request && response
-    records << RSpec::OpenAPI::RecordBuilder.build(self, example: example)
+  if example.metadata[:type] == :request && example.metadata[:openapi] != false
+    record = RSpec::OpenAPI::RecordBuilder.build(self, example: example)
+    records << record if record
   end
 end
 

data/lib/rspec/openapi/record.rb

@@ -5,8 +5,7 @@ RSpec::OpenAPI::Record = Struct.new(
   :query_params,          # @param [Hash]    - {:query=>"string"}
   :request_params,        # @param [Hash]    - {:request=>"body"}
   :request_content_type,  # @param [String]  - "application/json"
-  :controller,            # @param [String]  - "v1/statuses"
-  :action,                # @param [String]  - "show"
+  :summary,               # @param [String]  - "v1/statuses #show"
   :description,           # @param [String]  - "returns a status"
   :status,                # @param [Integer] - 200
   :response_body,         # @param [Object]  - {"status" => "ok"}

data/lib/rspec/openapi/record_builder.rb

@@ -1,25 +1,38 @@
+require 'action_dispatch'
 require 'rspec/openapi/record'
 
 class << RSpec::OpenAPI::RecordBuilder = Object.new
   # @param [RSpec::ExampleGroups::*] context
   # @param [RSpec::Core::Example] example
-  # @return [RSpec::OpenAPI::Record]
+  # @return [RSpec::OpenAPI::Record,nil]
   def build(context, example:)
-    # TODO: Support Non-Rails frameworks
-    request = context.request
-    response = context.response
-    route = find_route(request)
+    if rack_test?(context)
+      request = ActionDispatch::Request.new(context.last_request.env)
+      response = ActionDispatch::TestResponse.new(*context.last_response.to_a)
+    else
+      request = context.request
+      response = context.response
+    end
+
+    # Generate `path` and `summary` in a framework-friendly manner when possible
+    if defined?(Rails) && Rails.application
+      route = find_rails_route(request)
+      path = route.path.spec.to_s.delete_suffix('(.:format)')
+      summary = "#{route.requirements[:controller]} ##{route.requirements[:action]}"
+    else
+      path = request.path
+      summary = "#{request.method} #{request.path}"
+    end
 
     RSpec::OpenAPI::Record.new(
       method: request.request_method,
-      path: route.path.spec.to_s.delete_suffix('(.:format)'),
+      path: path,
       path_params: request.path_parameters,
       query_params: request.query_parameters,
-      request_params: request.request_parameters,
+      request_params: raw_request_params(request),
       request_content_type: request.content_type,
-      controller: route.requirements[:controller],
-      action: route.requirements[:action],
-      description: example.description,
+      summary: summary,
+      description: RSpec::OpenAPI.description_builder.call(example),
       status: response.status,
       response_body: response.parsed_body,
       response_content_type: response.content_type,
@@ -28,11 +41,24 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
 
   private
 
+  def rack_test?(context)
+    defined?(Rack::Test::Methods) && context.class < Rack::Test::Methods
+  end
+
   # @param [ActionDispatch::Request] request
-  def find_route(request)
+  def find_rails_route(request)
     Rails.application.routes.router.recognize(request) do |route|
       return route
     end
     raise "No route matched for #{request.request_method} #{request.path_info}"
   end
+
+  # workaround to get real request parameters
+  # because ActionController::ParamsWrapper overwrites request_parameters
+  def raw_request_params(request)
+    original = request.delete_header('action_dispatch.request.request_parameters')
+    request.request_parameters
+  ensure
+    request.set_header('action_dispatch.request.request_parameters', original)
+  end
 end

data/lib/rspec/openapi/schema_builder.rb

@@ -6,7 +6,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
       paths: {
         normalize_path(record.path) => {
           record.method.downcase => {
-            summary: "#{record.controller} ##{record.action}",
+            summary: record.summary,
             parameters: build_parameters(record),
             requestBody: build_request_body(record),
             responses: {
@@ -15,7 +15,8 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
                 content: {
                   normalize_content_type(record.response_content_type) => {
                     schema: build_property(record.response_body),
-                  },
+                    example: (record.response_body if example_enabled?),
+                  }.compact,
                 },
               },
             },
@@ -27,6 +28,10 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
   private
 
+  def example_enabled?
+    RSpec::OpenAPI.enable_example
+  end
+
   def build_parameters(record)
     parameters = []
 
@@ -37,7 +42,8 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         in: 'path',
         required: true,
         schema: build_property(try_cast(value)),
-      }
+        example: (try_cast(value) if example_enabled?),
+      }.compact
     end
 
     record.query_params.each do |key, value|
@@ -45,7 +51,8 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: key.to_s,
         in: 'query',
         schema: build_property(try_cast(value)),
-      }
+        example: (try_cast(value) if example_enabled?),
+      }.compact
     end
 
     return nil if parameters.empty?
@@ -60,7 +67,8 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
       content: {
         normalize_content_type(record.request_content_type) => {
           schema: build_property(record.request_params),
-        }
+          example: (record.request_params if example_enabled?),
+        }.compact
       }
     }
   end

data/lib/rspec/openapi/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module OpenAPI
-    VERSION = '0.1.5'
+    VERSION = '0.3.1'
   end
 end

data/rspec-openapi.gemspec

@@ -6,15 +6,15 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Takashi Kokubun']
   spec.email         = ['takashikkbn@gmail.com']
 
-  spec.summary       = %q{Generate OpenAPI specs from RSpec request specs}
-  spec.description   = %q{Generate OpenAPI specs from RSpec request specs}
+  spec.summary       = %q{Generate OpenAPI schema from RSpec request specs}
+  spec.description   = %q{Generate OpenAPI  from RSpec request specs}
   spec.homepage      = 'https://github.com/k0kubun/rspec-openapi'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
-  # spec.metadata['changelog_uri'] = 'TODO'
+  spec.metadata['changelog_uri'] = File.join(spec.homepage, 'blob/master/CHANGELOG.md')
 
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
@@ -23,5 +23,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.add_dependency 'actionpack'
   spec.add_dependency 'rspec'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.3.1
 platform: ruby
 authors:
 - Takashi Kokubun
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-20 00:00:00.000000000 Z
+date: 2020-07-13 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -24,13 +38,14 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Generate OpenAPI specs from RSpec request specs
+description: Generate OpenAPI  from RSpec request specs
 email:
 - takashikkbn@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/test.yml"
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
@@ -57,6 +72,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/k0kubun/rspec-openapi
   source_code_uri: https://github.com/k0kubun/rspec-openapi
+  changelog_uri: https://github.com/k0kubun/rspec-openapi/blob/master/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -72,8 +88,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.0.pre1
 signing_key: 
 specification_version: 4
-summary: Generate OpenAPI specs from RSpec request specs
+summary: Generate OpenAPI schema from RSpec request specs
 test_files: []