openapi_first 1.1.1 → 1.3.0

data/README.md

@@ -1,225 +0,0 @@
-# openapi_first
-
-OpenapiFirst helps to implement HTTP APIs based on an [OpenAPI](https://www.openapis.org/) API description. It supports OpenAPI 3.0 and 3.1. It offers request and response validation and it ensures that your implementation follows exactly the API description.
-
-## Contents
-
-<!-- TOC -->
-
-- [Manual use](#manual-use)
-- [Rack Middlewares](#rack-middlewares)
-  - [Request validation](#request-validation)
-  - [Response validation](#response-validation)
-- [Configuration](#configuration)
-- [Development](#development)
-  - [Benchmarks](#benchmarks)
-  - [Contributing](#contributing)
-
-<!-- /TOC -->
-
-## Manual use
-
-Load the API description:
-
-```ruby
-require 'openapi_first'
-
-definition = OpenapiFirst.load('petstore.yaml')
-```
-
-Validate request / response:
-
-```ruby
-
-# Find the request
-rack_request = Rack::Request.new(env) # GET /pets/42
-request = definition.request(rack_request)
-
-# Inspect the request and access parsed parameters
-request.known? # Is the request defined in the API description?
-request.content_type
-request.body # alias: parsed_body
-request.path_parameters # => { "pet_id" => 42 }
-request.query_parameters # alias: query
-request.params # Merged path and query parameters
-request.headers
-request.cookies
-request.request_method # => "get"
-request.path # => "/pets/42"
-request.path_definition # => "/pets/{pet_id}"
-
-# Validate the request
-request.validate # Returns OpenapiFirst:::Failure if validation fails
-request.validate! # Raises OpenapiFirst::RequestInvalidError or OpenapiFirst::NotFoundError if validation fails
-
-# Find the response
-rack_response = Rack::Response[*app.call(env)]
-response = request.response(rack_response) # or definition.response(rack_request, rack_response)
-
-# Inspect the response
-response.known? # Is the response defined in the API description?
-response.status # => 200
-response.content_type
-response.body
-request.headers # parsed response headers
-
-# Validate response
-response.validate # Returns OpenapiFirst::Failure if validation fails
-response.validate! # Raises OpenapiFirst::ResponseInvalidError or OpenapiFirst::ResponseNotFoundError if validation fails
-```
-
-OpenapiFirst uses [`multi_json`](https://rubygems.org/gems/multi_json).
-
-## Rack Middlewares
-
-All middlewares add a _request_ object to the current Rack env at `env[OpenapiFirst::REQUEST]`), which is in an instance of `OpenapiFirst::RuntimeRequest` that responds to `.params`, `.parsed_body` etc.
-
-This gives you access to the converted request parameters and body exaclty as described in your API description instead of relying on Rack alone to parse the request. This only includes query parameters that are defined in the API description. It supports every [`style` and `explode` value as described](https://spec.openapis.org/oas/latest.html#style-examples) in the OpenAPI 3.0 and 3.1 specs.
-
-### Request validation
-
-The request validation middleware returns a 4xx if the request is invalid or not defined in the API description.
-
-```ruby
-use OpenapiFirst::Middlewares::RequestValidation, spec: 'openapi.yaml'
-```
-
-#### Options
-
-| Name              | Possible values                                                          | Description                                                                                                                         |
-| :---------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `spec:`           |                                                                          | The path to the spec file or spec loaded via `OpenapiFirst.load`                                                                    |
-| `raise_error:`    | `false` (default), `true`                                                | If set to true the middleware raises `OpenapiFirst::RequestInvalidError` or `OpenapiFirst::NotFoundError` instead of returning 4xx. |
-| `error_response:` | `:default` (default), `:jsonapi`, Your implementation of `ErrorResponse` |
-
-Here in an example response body about an invalid request body. See also [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).
-
-```json
-http-status: 400
-content-type: "application/problem+json"
-
-{
-  "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"
-    }
-  ]
-}
-```
-
-openapi_first offers a [JSON:API](https://jsonapi.org/) error response as well:
-
-```ruby
-use OpenapiFirst::Middlewares::RequestValidation, spec: 'openapi.yaml, error_response: :jsonapi'
-```
-
-Here is an example error response:
-
-```json
-// http-status: 400
-// content-type: "application/vnd.api+json"
-
-{
-  "errors": [
-    {
-      "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": {
-        "pointer": "/data"
-      },
-      "title": "object at `/data` is missing required properties: mandatory",
-      "code": "required"
-    }
-  ]
-}
-```
-
-You can build your own custom error response with `error_response: MyCustomClass` that implements `OpenapiFirst::ErrorResponse`.
-
-#### readOnly / writeOnly properties
-
-Request validation fails if request includes a property with `readOnly: true`.
-
-Response validation fails if response body includes a property with `writeOnly: true`.
-
-### Response validation
-
-This middleware is especially useful when testing. It _always_ raises an error if the response is not valid.
-
-```ruby
-use OpenapiFirst::Middlewares::ResponseValidation, spec: 'openapi.yaml' if ENV['RACK_ENV'] == 'test'
-```
-
-#### Options
-
-| Name    | Possible values | Description                                                      |
-| :------ | --------------- | ---------------------------------------------------------------- |
-| `spec:` |                 | The path to the spec file or spec loaded via `OpenapiFirst.load` |
-
-## Configuration
-
-You can configure default options globally:
-
-```ruby
-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
-  # Configure if the response validation middleware should raise an exception (defaults to false)
-  config.request_validation_raise_error = true
-end
-```
-
-## Development
-
-Run `bin/setup` to install dependencies.
-
-See `bundle exec rake` to run the linter and the tests.
-
-Run `bundle exec rspec` to run the tests only.
-
-### Benchmarks
-
-[Results](https://gist.github.com/ahx/e6ffced58bd2e8d5baffb2f4d2c1f823)
-
-Run benchmarks:
-
-```sh
-cd benchmarks
-bundle
-bundle exec ruby benchmarks.rb
-```
-
-### Contributing
-
-If you have a question or an idea or found a bug don't hesitate to [create an issue](https://github.com/ahx/openapi_first/issues) or [start a discussion](https://github.com/ahx/openapi_first/discussions).
-
-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. 🤗

data/openapi_first.gemspec

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'openapi_first/version'
-
-Gem::Specification.new do |spec|
-  spec.name          = 'openapi_first'
-  spec.version       = OpenapiFirst::VERSION
-  spec.authors       = ['Andreas Haller']
-  spec.email         = ['andreas.haller@posteo.de']
-  spec.licenses      = ['MIT']
-
-  spec.summary       = 'Implement REST APIs based on OpenApi 3.x'
-  spec.homepage      = 'https://github.com/ahx/openapi_first'
-
-  if spec.respond_to?(:metadata)
-    spec.metadata['https://github.com/ahx/openapi_first'] = spec.homepage
-    spec.metadata['source_code_uri'] = 'https://github.com/ahx/openapi_first'
-    spec.metadata['changelog_uri'] = 'https://github.com/ahx/openapi_first/blob/main/CHANGELOG.md'
-    spec.metadata['rubygems_mfa_required'] = 'true'
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against ' \
-          'public gem pushes.'
-  end
-
-  spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`
-      .split("\x0")
-      .reject { |f| f.match(%r{^(test|spec|features|benchmarks|examples|bin)/}) }
-      .reject do |f|
-      %w[Dockerfile Jenkinsfile .tool-versions CODEOWNERS .rspec .rubocop.yml .tool-versions
-         Rakefile].include?(f)
-    end
-  end
-  spec.bindir        = 'exe'
-  spec.require_paths = ['lib']
-
-  spec.required_ruby_version = '>= 3.1.1'
-
-  spec.add_runtime_dependency 'json_refs', '~> 0.1', '>= 0.1.7'
-  spec.add_runtime_dependency 'json_schemer', '~> 2.1.0'
-  spec.add_runtime_dependency 'multi_json', '~> 1.15'
-  spec.add_runtime_dependency 'mustermann-contrib', '~> 3.0.0'
-  spec.add_runtime_dependency 'openapi_parameters', '>= 0.3.2', '< 2.0'
-  spec.add_runtime_dependency 'rack', '>= 2.2', '< 4.0'
-end