openapi

openAPIProxy - OpenAPI Configuration and Validation

Membrane's openAPIProxy offers support for OpenAPI and provides the following features:

• Configuration from OpenAPI
• Request and response validation against OpenAPI, including paths, parameters and JSON bodies.
• Rewriting of addresses
• Swagger UI integration

This page serves as a reference for the functions and configuration. See also the examples:

• api, UI and Swagger UI
• OpenAPI validation
• OpenAPI validation extended sample

The api is featured in Membrane version 5 and newer and supports OpenAPI version 2 and up.

Configuration

An api can be added to the proxies.xml configuration file. See the example in the openapi-proxy/ folder.

<router>
    <api port="2000">
        <openapi location="fruitshop-api.yml"/>
        <openapi dir="openapi"/>
        <openapi location="https://developer.lufthansa.com/swagger/export/21516"/>
        <openapi location="https://api.apis.guru/v2/specs/nowpayments.io/1.0.0/openapi.json"/>
        <openapi location="https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml"/>
    </api>
</router>

The spec element adds OpenAPI documents to the configuration. You can add *.json, *.yml and *.yaml files in a folder using the dir attribute or single local or remote files using the location attribute.

The addresses of the backend servers and the base-paths are taken from the OpenAPI specification. Suppose an OpenAPI document contains the servers field below. The proxy will match requests against the base-path /shop/v2 and in case of a match it will forward the request to the backend server api.predic8.de using TLS.

servers:
  - url: https://api.predic8.de/shop/v2

If the basepath does not match, the next API is checked.

It is also possible to configure the backend address using a target in the configuration. Then the addresses in the server field of the OpenAPI are ignored and the request is sent to the address from the target element.

<serviceProxy>
    <api port="2000">
        <openapi dir="openapi"/>
        <target host="api.predic8.de" port="8080"/>
    </api>
</serviceProxy>

OpenAPI Validation

Membrane can validate requests and responses against OpenAPI definitions and check:

• Methods and paths
• Query and path parameters
• Content types
• Status codes
• Body content according to the JSON Schema component definitions

Validation can be activated for requests and responses separately. Set validationDetails to no if you do not want to send validation errors in detail to the client.

<openapi location="fruitshop-api.yml" 
      validateRequests="yes" 
      validateResponses="yes" 
      validationDetails="yes"/>

As an alternative way validation can be turned on in the OpenAPI documents using the x-membrane-validation field. The configuration in the proxies.xml file will overwrite the x-membrane-validation field.

x-membrane-validation:
  requests: true
  responses: true
  details: false

Overview and Swagger UI

The api has a UI that can be reached on its port e.g. http://localhost:2000/api-docs. Follow the links on the left to access the Swagger UI or the link on the right to download the OpenAPI document.

To get a JSON description of the deployed OpenAPI documents call the same <a href="curl http://localhost:2000/api-docs">URL</a> outside the browser e.g. in curl or Postman:

curl http://localhost:2000/api-docs

OpenAPI Overview

The api-docs plugin provides a web page listing all deployed APIs, facilitating effortless navigation to the Swagger UI.

Configuration

To utilize the plugin, simply include the <apiDocs /> tag at an endpoint.

<router>

   <api port="2000">
       <apiDocs />
   </api>

    <api port="2001">
        <openapi location="https://developer.lufthansa.com/swagger/export/21516"/>
    </api>

    <api port="2002">
        <openapi location="https://api.apis.guru/v2/specs/nowpayments.io/1.0.0/openapi.json"/>
    </api>

    <api port="2003">
        <openapi location="https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml"/>
    </api>

</router>

Usage

Access http://localhost:2000/ to see the overview.

API List: The overview displays all deployed APIs.

Swagger UI: Click on any API to access its Swagger UI.

Download OpenAPI Document: Each API entry provides a link to download its OpenAPI document.

Rewriting of Server Addresses

When an API is published on a gateway the OpenAPI must point to the gateway instead of pointing to the backend server. Rewriting changes the backend addresses of an OpenAPI document to the address of the gateway.

The api exposes the OpenAPI specifications in the UI and over an endpoint:

/api-docs/<>

The addresses in the OpenAPI's _/servers_ field are rewritten to the address the endpoint is called on the gateway. Suppose the OpenAPI has the following servers field:

```yaml
servers:
- url: "http://fruit-shop.api-demos.svc.ack.predic8.de:8080/shop/v2"

And you send a request to Membrane like this:

GET /api-docs/fruit-shop-api-v1-0
Host: api.predic8.de:443

Then the rewriter of the api will turn the servers field into:

servers:
- url: "https://api.predic8.de:443/shop/v2"

If you use the rewritten OpenAPI-document for your client, then requests will be sent to Membrane at https://api.predic8.de:443/shop/v2 and then forwarded to the destination http://fruit-shop.api-demos.svc.ack.predic8.de:8080/shop/v2.

SSL/TLS

TLS for incoming and outgoing connections can be configured in the same way as for the serviceProxy. See the documentation for the ssl element.

<api port="2000">
    <openapi dir="openapi"/>
    <ssl>
        <keystore location="..."/>
        <truststore location="..."/>
    </ssl>
    <target host="api.predic8.de" port="443">
        <ssl>
            <keystore location="..."/>
            <truststore location="..."/>
        </ssl>
    </target>
</api>

Plugins / Interceptors

The behaviour of the api can be modified like other proxies with plugins and interceptors. See the examples and the configuration reference.

<api port="2000">
    <openapi dir="openapi"/>
    <tokenValidator endpoint="https://login.predic8.de/oauth2/userinfo"/>
    <log/>
</api>

Ids of OpenAPI Documents

Membrane needs unique ids for each OpenAPI document to provide a Swagger UI and the /api-docs/{id} endpoint. The id is generated from the title and version of the API. For the following document Membrane will generate the id fruit-shop-api-v1-0.

info:
  title: "Fruit Shop API"
  version: "2.0"

To give an API a custom id the x-membrane-id field can be used.

info:
  title: Fruit Shop API
  version: '2.0'
  x-membrane-id: fruitshop

To the id the version will be appended so the id will be fruitshop-v-1-0.