OpenAPI Configuration and Validation

Membrane offers support for OpenAPI, providing the following features:

• Configuration from OpenAPI
• Validation against OpenAPI
• Rewriting of addresses
• Swagger UI integration

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

• OpenAPI Configuration and Swagger UI
• OpenAPI validation
• OpenAPI validation extended sample

The OpenAPI support is featured in Membrane version 5 and newer.

Configuration

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

<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>

The openapi 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 basepaths are taken from the OpenAPI specification. Suppose an OpenAPI document contains the servers field below. The proxy will match requests against the basepath /shop 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

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. In that case, the addresses in the server field of the OpenAPI are ignored, and the request is sent to the address from the target element.

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

OpenAPI Validation

Membrane can validate requests and responses against OpenAPI definitionsand 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"/>

Alternatively, 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 openAPIProxy has a UI that can be reached on its port, for example, http://localhost:2000/api-doc. 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 URL outside of the browser, for example, using curl or Postman:

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

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 openAPIProxy exposes the OpenAPI specifications in the UI and over an endpoint:

/api_docs/<<id of the api>>

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:

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

And you send a request to Membrane like this:

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

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

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

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

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 openAPIProxy 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: "1.0"

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

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

The id will include the version, resulting in fruitshop-v-1-0.