Generate Response Headers

README.md

@@ -137,9 +137,12 @@ RSpec::OpenAPI.info = {
   }
 }
 
-# Set `headers` - generate parameters with headers for a request
+# 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' }]
 

lib/rspec/openapi.rb

@@ -11,8 +11,18 @@ module RSpec::OpenAPI
   @request_headers = []
   @servers = []
   @example_types = %i[request]
+  @response_headers = []
 
   class << self
-    attr_accessor :path, :comment, :enable_example, :description_builder, :info, :application_version, :request_headers, :servers, :example_types
+    attr_accessor :path,
+                  :comment,
+                  :enable_example,
+                  :description_builder,
+                  :info,
+                  :application_version,
+                  :request_headers,
+                  :servers,
+                  :example_types,
+                  :response_headers
   end
 end

lib/rspec/openapi/record.rb

@@ -11,6 +11,7 @@
   :description,           # @param [String]  - "returns a status"
   :status,                # @param [Integer] - 200
   :response_body,         # @param [Object]  - {"status" => "ok"}
+  :response_headers,      # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
   :response_content_type, # @param [String]  - "application/json"
   :response_content_disposition, # @param [String]  - "inline"
   keyword_init: true,

lib/rspec/openapi/record_builder.rb

@@ -42,6 +42,12 @@ def build(context, example:)
 
     metadata_options = example.metadata[:openapi] || {}
 
+    response_headers = RSpec::OpenAPI.response_headers.each_with_object([]) do |header, headers_arr|
+      header_key = header
+      header_value = response.headers[header_key]
+      headers_arr << [header_key, header_value] if header_value
+    end
+
     RSpec::OpenAPI::Record.new(
       method: request.request_method,
       path: path,
@@ -55,6 +61,7 @@ def build(context, example:)
       description: metadata_options[:description] || RSpec::OpenAPI.description_builder.call(example),
       status: response.status,
       response_body: response_body,
+      response_headers: response_headers,
       response_content_type: response.media_type,
       response_content_disposition: response.header["Content-Disposition"],
     ).freeze

lib/rspec/openapi/schema_builder.rb

@@ -6,6 +6,9 @@ def build(record)
       description: record.description,
     }
 
+    response_headers = build_response_headers(record)
+    response[:headers] = response_headers unless response_headers.empty?
+
     if record.response_body
       disposition = normalize_content_disposition(record.response_content_disposition)
       response[:content] = {
@@ -81,6 +84,18 @@ def build_parameters(record)
     parameters
   end
 
+  def build_response_headers(record)
+    headers = {}
+
+    record.response_headers.each do |key, value|
+      headers[key] = {
+        schema: build_property(try_cast(value)),
+      }.compact
+    end
+
+    headers
+  end
+
   def build_parameter_name(key, value)
     key = key.to_s
     if value.is_a?(Hash) && (value_keys = value.keys).size == 1

spec/rails/app/controllers/tables_controller.rb

@@ -4,6 +4,7 @@ class TablesController < ApplicationController
   before_action :authenticate
 
   def index
+    response.set_header('X-Cursor', 100)
     render json: [find_table]
   end
 

spec/rails/doc/openapi.json

@@ -101,6 +101,13 @@
                   }
                 ]
               }
+            },
+            "headers": {
+              "X-Cursor": {
+                "schema": {
+                  "type": "integer"
+                }
+              }
             }
           }
         },
@@ -647,4 +654,4 @@
       }
     }
   }
-}
+}

spec/rails/doc/openapi.yaml

@@ -93,10 +93,14 @@ paths:
                 database:
                   id: 2
                   name: production
-                null_sample: 
+                null_sample:
                 storage_size: 12.3
                 created_at: '2020-07-17T00:00:00+00:00'
                 updated_at: '2020-07-17T00:00:00+00:00'
+          headers:
+            X-Cursor:
+              schema:
+                type: integer
         '401':
           description: does not return tables if unauthorized
           content:
@@ -165,7 +169,7 @@ paths:
                 database:
                   id: 2
                   name: production
-                null_sample: 
+                null_sample:
                 storage_size: 12.3
                 created_at: '2020-07-17T00:00:00+00:00'
                 updated_at: '2020-07-17T00:00:00+00:00'
@@ -218,7 +222,7 @@ paths:
                 database:
                   id: 2
                   name: production
-                null_sample: 
+                null_sample:
                 storage_size: 12.3
                 created_at: '2020-07-17T00:00:00+00:00'
                 updated_at: '2020-07-17T00:00:00+00:00'
@@ -310,7 +314,7 @@ paths:
                 database:
                   id: 2
                   name: production
-                null_sample: 
+                null_sample:
                 storage_size: 12.3
                 created_at: '2020-07-17T00:00:00+00:00'
                 updated_at: '2020-07-17T00:00:00+00:00'
@@ -362,7 +366,7 @@ paths:
                 database:
                   id: 2
                   name: production
-                null_sample: 
+                null_sample:
                 storage_size: 12.3
                 created_at: '2020-07-17T00:00:00+00:00'
                 updated_at: '2020-07-17T00:00:00+00:00'

spec/rails/doc/smart/expected.yaml

@@ -56,6 +56,10 @@ paths:
                 storage_size: 12.3
                 created_at: '2020-07-17T00:00:00+00:00'
                 updated_at: '2020-07-17T00:00:00+00:00'
+          headers:
+            X-Cursor:
+              schema:
+                type: integer
         '401':
           description: does not return tables if unauthorized
           content:

spec/requests/rails_smart_merge_spec.rb

@@ -6,6 +6,7 @@
 require 'rspec/rails'
 
 RSpec::OpenAPI.request_headers = %w[X-Authorization-Token]
+RSpec::OpenAPI.response_headers = %w[X-Cursor]
 RSpec::OpenAPI.path = File.expand_path("../rails/doc/smart/openapi.#{ENV['OPENAPI_OUTPUT']}", __dir__)
 RSpec::OpenAPI.comment = <<~COMMENT
   This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi
@@ -30,6 +31,7 @@
         # These new params replace them in old spec
         get '/tables', params: { page: '42', per: '10' },
             headers: { authorization: 'k0kubun', "X-Authorization-Token": 'token' }
+        response.set_header('X-Cursor', 100)
         expect(response.status).to eq(200)
       end
     end

spec/requests/rails_spec.rb

@@ -6,6 +6,7 @@
 require 'rspec/rails'
 
 RSpec::OpenAPI.request_headers = %w[X-Authorization-Token]
+RSpec::OpenAPI.response_headers = %w[X-Cursor]
 RSpec::OpenAPI.path = File.expand_path("../rails/doc/openapi.#{ENV['OPENAPI_OUTPUT']}", __dir__)
 RSpec::OpenAPI.comment = <<~COMMENT
   This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi