openapi_first 0.7.0.alpha1 → 3.1.0.beta1

data/README.md

@@ -1,204 +1,450 @@
-# OpenapiFirst
+# openapi_first
 
-OpenapiFirst helps to implement HTTP APIs based on an [OpenApi](https://www.openapis.org/) API description. The idea is that you create an API description first, then add a method that returns data and implements your business logic and be done.
+openapi_first is a Ruby gem for request / response validation and contract-testing against an [OpenAPI](https://www.openapis.org/) 3.0 or 3.1 Openapi API description (OAD). It makes an APIFirst workflow easy and reliable.
 
-## TL;DR
+## Usage
 
-Start with writing an OpenAPI file that describes the API, which you are about to write. Use a [validator](https://github.com/stoplightio/spectral/) to make sure the file is valid.
-In the following examples, the OpenAPI file is named `openapi/openapi.yaml`.
-
-Now implement your API:
+Configure
+```ruby
+OpenapiFirst.register('openapi/openapi.yaml')
+```
 
+Use an OAD to validate incoming requests:
 ```ruby
-module Pets
-  def self.find_pet(params, res)
-    {
-      id: params['id'],
-      name: 'Oscar'
-    }
-  end
-end
+use OpenapiFirst::Middlewares::RequestValidation
+```
 
-# In config.ru:
+Turn your request tests into [contract tests](#contract-testing) against an OAD:
+```ruby
+# spec_helper.rb
 require 'openapi_first'
-run OpenapiFirst.app('./openapi/openapi.yaml', namespace: Pets)
-```
+OpenapiFirst::Test.setup
 
-The above will:
+require 'my_app'
+RSpec.configure do |config|
+  config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+end
+```
 
-- Validate the request and respond with 400 if the request does not match with your API description
-- Map the request to a method call `Pets.find_pet` based on the `operationId` in the API description
-- Set the response content type according to your spec (here with the default status code `200`)
+## Contents
 
-Handler functions (`find_pet`) are called with two arguments:
+<!-- TOC -->
 
-- `params` - Holds the parsed request body, filtered query params and path parameters
-- `res` - Holds a Rack::Response that you can modify if needed
-  If you want to access to plain Rack env you can call `params.env`.
+- [Configuration](#configuration)
+- [Rack Middlewares](#rack-middlewares)
+  - [Request validation](#request-validation)
+  - [Response validation](#response-validation)
+- [Contract testing](#contract-testing)
+  - [Test assertions](#test-assertions)
+- [Manual use](#manual-use)
+- [Framework integration](#framework-integration)
+- [Hooks](#hooks)
+- [Alternatives](#alternatives)
+- [Frequently Asked Questions](#frequently-asked-questions)
+- [Development](#development)
+  - [Benchmarks](#benchmarks)
+  - [Contributing](#contributing)
 
-### Handling only certain paths
+<!-- /TOC -->
 
-You can filter the URIs that should be handled by pass ing `only` to `OpenapiFirst.load`:
+## Configuration
 
+You should register OADs globally so you don't have to load the file multiple times or to refernce them by Symbol (like :v1 in this example).
 ```ruby
-spec = OpenapiFirst.load './openapi/openapi.yaml', only: '/pets'.method(:==)
-run OpenapiFirst.app(spec, namespace: Pets)
+OpenapiFirst.configure do |config|
+  config.register('openapi/openapi.yaml') # :default
+  config.register('openapi/v1.openapi.yaml', as: :v1)
+end
 ```
 
-### Usage as Rack middleware
+You can configure default options globally:
 
 ```ruby
-# Just like the above, except the last line
-# ...
-run OpenapiFirst.middleware('./openapi/openapi.yaml', namespace: Pets)
+OpenapiFirst.configure do |config|
+  # Specify which plugin is used to render error responses returned by the request validation middleware (defaults to :default)
+  config.request_validation_error_response = :jsonapi
+end
 ```
 
-When using the middleware, all requests that are not part of the API description will be passed to the next app.
-
-### Try it out
-
-See [examples](examples).
-
-
-## Installation
-
-Add this line to your application's Gemfile:
+or configure per instance:
 
 ```ruby
-gem 'openapi_first'
+OpenapiFirst.load('openapi.yaml') do |config|
+  config.request_validation_error_response = :jsonapi
+end
 ```
 
-OpenapiFirst uses [`multi_json`](https://rubygems.org/gems/multi_json).
+## Rack Middlewares
 
-## Handlers
+### Request validation
 
-OpenapiFirst maps the HTTP request to a method call based on the [operationId](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operation-object) in your API description.
+The request validation middleware returns a 4xx if the request is invalid or not defined in the API description. It adds a request object to the current Rack environment at `env[OpenapiFirst::REQUEST]` with the request parameters parsed exactly as described in your API description plus access to meta information from your API description. See _[Manual use](#manual-use)_ for more details about that object.
 
-It works like this:
-
-- "create_pet" or "createPet" or "create pet" calls `MyApi.create_pet(params, response)`
-- "some_things.create" calls: `MyApi::SomeThings.create(params, response)`
-- "pets#create" calls: `MyApi::Pets::Create.new.call(params, response)`
-
-These handler methods are called with two arguments:
+```ruby
+use OpenapiFirst::Middlewares::RequestValidation
 
-- `params` - Holds the parsed request body, filtered query params and path parameters
-- `res` - Holds a Rack::Response that you can modify if needed
+# Pass `raise_error: true` to raise an error if request is invalid:
+use OpenapiFirst::Middlewares::RequestValidation, raise_error: true
+```
 
-You can call `params.env` to access the Rack env (just like in [Hanami actions](https://guides.hanamirb.org/actions/parameters/))
+#### Error responses
 
-There are two ways to set the response body:
+openapi_first produces a useful machine readable error response that can be customized.
+The default response looks like this. See also [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).
 
-- Calling `res.write "things"` (see [Rack::Response](https://www.rubydoc.info/github/rack/rack/Rack/Response))
-- Returning a value from the function (see example above) (this will always converted to JSON)
+```json
+http-status: 400
+content-type: "application/problem+json"
 
-## Request validation
+{
+  "title": "Bad Request Body",
+  "status": 400,
+  "errors": [
+    {
+      "message": "value at `/data/name` is not a string",
+      "pointer": "/data/name",
+      "code": "string"
+    },
+    {
+      "message": "number at `/data/numberOfLegs` is less than: 2",
+      "pointer": "/data/numberOfLegs",
+      "code": "minimum"
+    },
+    {
+      "message": "object at `/data` is missing required properties: mandatory",
+      "pointer": "/data",
+      "code": "required"
+    }
+  ]
+}
+```
 
-If the request is not valid, these middlewares return a 400 status code with a body that describes the error.
+openapi_first offers a [JSON:API](https://jsonapi.org/) error response by passing `error_response: :jsonapi`:
 
-The error responses conform with [JSON:API](https://jsonapi.org).
+```ruby
+use OpenapiFirst::Middlewares::RequestValidation, 'openapi.yaml', error_response: :jsonapi
+```
 
-Here's an example response body for a missing query parameter "search":
+<details>
+<summary>See details of JSON:API error response</summary>
 
 ```json
-http-status: 400
-content-type: "application/vnd.api+json"
+// http-status: 400
+// content-type: "application/vnd.api+json"
 
 {
   "errors": [
     {
-      "title": "is missing",
+      "status": "400",
+      "source": {
+        "pointer": "/data/name"
+      },
+      "title": "value at `/data/name` is not a string",
+      "code": "string"
+    },
+    {
+      "status": "400",
+      "source": {
+        "pointer": "/data/numberOfLegs"
+      },
+      "title": "number at `/data/numberOfLegs` is less than: 2",
+      "code": "minimum"
+    },
+    {
+      "status": "400",
       "source": {
-        "parameter": "search"
-      }
+        "pointer": "/data"
+      },
+      "title": "object at `/data` is missing required properties: mandatory",
+      "code": "required"
     }
   ]
 }
 ```
 
-### Parameter validation
+</details>
+
+#### Custom error responses
 
-The middleware filteres all top-level query parameters and paths parameters and tries to convert numeric values. Meaning, if you have an `:something_id` path with `type: integer`, it will try convert the value to an integer.
-Note that is currently does not convert date, date-time or time formats and that conversion is currently on done for path and query parameters, but not for request bodies.
+You can build your own custom error response with `error_response: MyCustomClass` that implements `OpenapiFirst::ErrorResponse`.
+You can define custom error responses globally by including / implementing `OpenapiFirst::ErrorResponse` and register it via `OpenapiFirst.register_error_response(my_name, MyCustomErrorResponse)` and set `error_response: my_name`.
 
-If you want to forbid _nested_ query parameters you will need to use [`additionalProperties: false`](https://json-schema.org/understanding-json-schema/reference/object.html#properties) in your query parameter JSON schema.
+### Response validation
 
-_OpenapiFirst always treats query parameters like [`style: deepObject`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#style-values), **but** it just works with nested objects (`filter[foo][bar]=baz`) (see [this discussion](https://github.com/OAI/OpenAPI-Specification/issues/1706))._
+This middleware raises an error by default if the response is not valid.
+This can be useful in a test or staging environment, especially if you are adopting OpenAPI for an existing implementation.
+
+```ruby
+use OpenapiFirst::Middlewares::ResponseValidation if ENV['RACK_ENV'] == 'test'
+
+# Pass `raise_error: false` to not raise an error:
+use OpenapiFirst::Middlewares::ResponseValidation, raise_error: false
+```
 
-### Request body validation
+If you are adopting OpenAPI you can use these options together with [hooks](#hooks) to get notified about requests/responses that do match your API description.
 
-The middleware will return a `415` if the requests content type does not match or `400` if the request body is invalid.
-This will add the parsed request body to `env[OpenapiFirst::REQUEST_BODY]`.
+## Contract Testing
 
-### Header, Cookie, Path parameter validation
+You can see your OpenAPI API description as a contract that your clients can rely on as how your API behaves. There are two aspects of contract testing: Validation and Coverage. By validating requests and responses, you can avoid that your API implementation processes requests or returns responses that don't match your API description. To make sure your _whole_ API description is implemented, openapi_first can check that all of your API description is covered when you test your API with [rack-test](https://github.com/rack/rack-test).
 
-tbd.
+Here is how to set it up:
 
-## Response validation
+1. Setup the test mode
+    ```ruby
+    # spec_helper.rb
+    require 'openapi_first'
+    OpenapiFirst::Test.setup
+    ```
+2. Observe your application. You can do this in multiple ways:
+    - Add an `app` method to your tests (which is called by rack-test) that wraps your application with silent request / response validation.
+      ```ruby
+      module RequestSpecHelpers
+        def app
+          OpenapiFirst::Test.app(MyApp)
+        end
+      end
 
-Response validation is useful to make sure your app responds as described in your API description. You usually do this in your tests using [rack-test](https://github.com/rack-test/rack-test).
+      RSpec.configure do |config|
+        config.include RequestSpecHelpers, type: :request
+      end
+      ```
+
+      Or do this by creating a Module and including it to add an "app" method.
+
+      ```ruby
+      RSpec.configure do |config|
+        config.include OpenapiFirst::Test::Methods[MyApp], type: :request
+      end
+      ```
+3. Run your tests. The Coverage feature will tell you about missing or invalid requests/responses:
+      ```
+      ✓ GET /stations
+        ✓ 200(application/json)
+        ❌ 200(application/xml) – No responses tracked!
+        ❌ 400(application/problem+json) – No responses tracked!
+      ```
+
+      Now add tests for all those "❌" to make them "✓" and you're green!
+
+> [!NOTE]
+> Check out [faraday-openapi](https://codeberg.org/ahx/faraday-openapi) to have your API _client_ validate request/responses against an OAD, which is useful to validate HTTP mocks during testing.
+
+### Configure test coverage
+
+OpenapiFirst::Test raises an error when a response status is not defined except for 404 and 500. You can change this:
 
 ```ruby
-# In your test (rspec example):
-require 'openapi_first'
-spec = OpenapiFirst.load('petstore.yaml')
-validator = OpenapiFirst::ResponseValidator.new(spec)
+OpenapiFirst::Test.setup do |test|
+  test.ignored_unknown_status << 403
+end
+```
+
+Or you can ignore all unknown response status:
+
+```ruby
+OpenapiFirst::Test.setup do |test|
+  test.ignore_unknown_response_status = true
+end
+```
+
+Exclude certain _responses_ from coverage with `skip_coverage`:
 
-expect(validator.validate(last_request, last_response).errors).to be_empty
+```ruby
+OpenapiFirst::Test.setup do |test|
+  test.skip_response_coverage do |response_definition|
+    response_definition.status == '5XX'
+  end
+end
 ```
 
-## Coverage
+Skip coverage for a request and all responses alltogether of a route with `skip_coverage`:
 
-(This is a bit experimental. Please try it out and give feedback.)
+```ruby
+OpenapiFirst::Test.setup do |test|
+  test.skip_coverage do |path, request_method|
+    path == '/bookings/{bookingId}' && requests_method == 'DELETE'
+  end
+end
+```
 
-`OpenapiFirst::Coverage` helps you make sure, that you have called all endpoints of your OAS file when running tests via `rack-test`.
+OpenapiFirst::Test raises an error when a request is not defined. You can deactivate this with:
 
 ```ruby
-# In your test (rspec example):
-require 'openapi_first/coverage'
+OpenapiFirst::Test.setup do |test|
+  test.ignore_unknown_requests = true
+end
+```
+
+### Test assertions
+
+> [!WARNING]
+> You probably don't need this. Just setup [Contract testing and API coverage](#contract-testing) and use your normal assertions.
+
+openapi_first ships with a simple but powerful Test method `assert_api_conform` to run request and response validation in your tests without using the middlewares. This is designed to be used with rack-test.
 
-describe MyApp do
+Here is how to use it with RSpec, but MiniTest works just as good:
+
+```ruby
+# spec_helper.rb
+OpenapiFirst::Test.setup do |test|
+  test.register(File.join(__dir__, '../examples/openapi.yaml'), as: :example_app)
+end
+```
+
+
+Inside your test :
+```ruby
+RSpec.describe 'Example App' do
   include Rack::Test::Methods
+  include OpenapiFirst::Test::Methods[App]
 
-  before(:all) do
-    spec = OpenapiFirst.load('petstore.yaml')
-    @app_wrapper = OpenapiFirst::Coverage.new(MyApp, spec)
+  it 'is API conform' do
+    get '/'
+    assert_api_conform(status: 200)
   end
+end
+```
 
-  after(:all) do
-    message = "The following paths have not been called yet: #{@app_wrapper.to_be_called}"
-    expect(@app_wrapper.to_be_called).to be_empty
-  end
+## Manual use
+
+Load the API description:
+
+```ruby
+require 'openapi_first'
+
+definition = OpenapiFirst.load('openapi.yaml')
+```
+
+### Validate request
+
+```ruby
+validated_request = definition.validate_request(rack_request)
+
+# Inspect the request and access parsed parameters
+validated_request.valid?
+validated_request.invalid?
+validated_request.error # => Failure object or nil
+validated_request.parsed_body # => The parsed request body (Hash)
+validated_request.parsed_query # A Hash of query parameters that are defined in the API description, parsed exactly as described.
+validated_request.parsed_path_parameters
+validated_request.parsed_headers
+validated_request.parsed_cookies
+validated_request.parsed_params # Merged parsed path, query parameters and request body
+# Access the Openapi 3 Operation Object Hash
+validated_request.operation['x-foo']
+validated_request.operation['operationId'] => "getStuff"
+# or the whole request definition
+validated_request.request_definition.path # => "/pets/{petId}"
+validated_request.request_definition.operation_id # => "showPetById"
+
+# Or you can raise an exception if validation fails:
+definition.validate_request(rack_request, raise_error: true) # Raises OpenapiFirst::RequestInvalidError or OpenapiFirst::NotFoundError if request is invalid
+```
+
+### Validate response
+
+```ruby
+validated_response = definition.validate_response(rack_request, rack_response)
+
+# Inspect the response and access parsed parameters and
+validated_response.valid?
+validated_response.invalid?
+validated_response.error # => Failure object or nil
+validated_response.status # => 200
+validated_response.parsed_body
+validated_response.parsed_headers
+
+# Or you can raise an exception if validation fails:
+definition.validate_response(rack_request,rack_response, raise_error: true) # Raises OpenapiFirst::ResponseInvalidError or OpenapiFirst::ResponseNotFoundError
+```
+
+## Hooks
+
+You can integrate your code at certain points during request/response validation via hooks.
+
+Available hooks:
 
-  # Overwrite `#app` to make rack-test call the wrapped app
-  def app
-    @app_wrapper
+- `after_request_validation`
+- `after_response_validation`
+- `after_request_parameter_property_validation`
+- `after_request_body_property_validation`
+
+Setup per per instance:
+
+```ruby
+OpenapiFirst.load('openapi.yaml') do |config|
+  config.after_request_validation do |validated_request|
+    validated_request.valid? # => true / false
+  end
+  config.after_response_validation do |validated_response, request|
+    if validated_response.invalid?
+      warn "#{request.request_method} #{request.path}: #{validated_response.error.message}"
+    end
   end
+end
+```
 
-  it 'does things' do
-    get '/i/my/stuff'
-    # …
+Setup globally:
+
+```ruby
+OpenapiFirst.configure do |config|
+  config.after_request_parameter_property_validation do |data, property, property_schema|
+    data[property] = Date.iso8601(data[property]) if property_schema['format'] == 'date'
   end
 end
 ```
 
-## Mocking
+## Framework integration
 
-Out of scope. Use [Prism](https://github.com/stoplightio/prism) or [fakeit](https://github.com/JustinFeng/fakeit).
+Using rack middlewares is supported in probably all Ruby web frameworks.
+
+The contract testing feature is designed to be used via rack-test, which should be compatible all Ruby web frameworks as well.
+
+That aside, closer integration with specific frameworks like Sinatra, Hanami, Roda or others would be great. If you have ideas, pain points or PRs, please don't hesitate to [share](https://github.com/ahx/openapi_first/discussions).
 
 ## Alternatives
 
-This gem is inspired by [committee](https://github.com/interagent/committee), which has much more features like response stubs or support for Hyper-Schema or OpenAPI 2.
+This gem was inspired by [committee](https://github.com/interagent/committee) (Ruby) and [Connexion](https://github.com/spec-first/connexion) (Python).
+Here is a [feature comparison between openapi_first and committee](https://gist.github.com/ahx/1538c31f0652f459861713b5259e366a).
+
+## Frequently Asked Questions
+
+### How can I adapt request paths that don't match my schema?
+
+Let's say you have `openapi.yaml` like this:
+
+```yaml
+servers:
+  - url: https://yourhost/api
+paths:
+  # The actual endpoint URL is https://yourhost/api/resource
+  /resource:
+```
+
+Here your OpenAPI schema defines endpoints starting with `/resource` but your actual application is mounted at `/api/resource`. You can bridge the gap by transforming the path via the `path:` configuration:
+
+```ruby
+oad = OpenapiFirst.load('openapi.yaml') do |config|
+  config.path = ->(req) { request.path.delete_prefix('/api') }
+end
+use OpenapiFirst::Middlewares::RequestValidation, oad
+```
 
 ## Development
 
+Run `git submodule update --init` to initialize the git submodules.
+
 Run `bin/setup` to install dependencies.
 
-Run `bundle exec rspec` to run the tests.
+See `bundle exec rake` to run the linter and the tests.
+
+Run `bundle exec rspec` to run the tests only.
+
+### Benchmarks
 
-See `bundle exec rake -T` for rubygems related tasks.
+[Results](https://gist.github.com/ahx/e6ffced58bd2e8d5baffb2f4d2c1f823)
 
-### Run benchmarks
+Run benchmarks:
 
 ```sh
 cd benchmarks
@@ -206,8 +452,8 @@ bundle
 bundle exec ruby benchmarks.rb
 ```
 
-## Contributing
+### Contributing
 
-If you have a question or an idea or found a bug don't hesitate to [create an issue on GitHub](https://github.com/ahx/openapi_first/issues).
+If you have a question or an idea or found a bug, don't hesitate to create an issue [on Github](https://github.com/ahx/openapi_first) or [Codeberg](https://codeberg.org/ahx/openapi_first) or say hi on [Mastodon (ruby.social)](https://ruby.social/@ahx).
 
 Pull requests are very welcome as well, of course. Feel free to create a "draft" pull request early on, even if your change is still work in progress. 🤗