LIGHT

  • News
  • Docs
  • Community
  • Reddit
  • GitHub

Multiple Specifications

For most REST APIs, there is only one specification file openapi.yaml will be configured per instance. With the specification loaded during the startup, the JWT security can use it to verify the scopes per endpoint, and the schema validator can use it to validate the request and response based on the same specification.

The above setup covers 99 percent of the use cases in the light-rest-4j applications. However, with light-gateway widely replacing centralized monolithic gateways by our customers, there are two cases where one service instance uses multiple specifications are required.

Case1: The light-gateway is a shared gateway for a group of services, and security verification and request validation are done on the gateway to filter the requests before routing to the downstream APIs.

Case2: The light-gateway is installed on the same host along with several legacy services to address cross-cutting concerns. In this case, the gateway instance must load all the backend services specifications for security verification and schema validation.

To enable multiple specs support in the light-rest-4j framework, we have updated the openapi-parse to update that OpenApiHelper to be not a singleton.

Also, we have updated the OpenApiHandler in the openapi-meta module to load multiple specifications based on the openapi-handler.yml configuration.

Subsequently, we updated the openapi-security and openapi-validator to leverage the multiple specifications based on the configuration.

Configuration

To support multiple specifications, we have added a new config file named openapi-handler.yml

# openapi-handler.yml
# This configuration file is used to support multiple OpenAPI specifications in the same light-rest-4j instance.
# An indicator to allow multiple openapi specifications. Default to false which only allow one spec named openapi.yml or openapi.yaml or openapi.json.
multipleSpec: ${openapi-handler.multipleSpec:false}
# When the OpenApiHandler is used in a shared gateway and some backend APIs have no specifications deployed on the gateway, the handler will return
# an invalid request path error to the client. To allow the call to pass through the OpenApiHandler and route to the backend APIs, you can set this
# flag to true. In this mode, the handler will only add the endpoint specification to the auditInfo if it can find it. Otherwise, it will pass through.
ignoreInvalidPath: ${openapi-handler.ignoreInvalidPath:false}
# Path to spec mapping. One or more base paths can map to the same specifications. The key is the base path and the value is the specification name.
# If users want to use multiple specification files in the same instance, each specification must have a unique base path and it must be set as key.
pathSpecMapping: ${openapi-handler.pathSpecMapping:}
#   v1: openapi-v1
#   v2: openapi-v2

By default, the multipleSpec indicator is set to false. So the server is loading only one openapi.yaml by default unless this flag is changed in the values.yml config file to overwrite the default or you can externalize the openapi-handler.yml to the config folder with the property changed to true.

When the multipleSpec is true, you have to provide a mapping between the basePath to the specification file name without extension.

Here is an example of openapi-handler.yml that overwrites the default one from the openapi-meta module.

# openapi-handler.yml
# This configuration file is used to support multiple OpenAPI specifications in the same light-rest-4j instance.
# An indicator to allow multiple openapi specifications. Default to false which only allow one spec named openapi.yml or openapi.yaml or openapi.json.
multipleSpec: ${openapi-handler.multipleSpec:true}
# When the OpenApiHandler is used in a shared gateway and some backend APIs have no specifications deployed on the gateway, the handler will return
# an invalid request path error to the client. To allow the call to pass through the OpenApiHandler and route to the backend APIs, you can set this
# flag to true. In this mode, the handler will only add the endpoint specification to the auditInfo if it can find it. Otherwise, it will pass through.
ignoreInvalidPath: ${openapi-handler.ignoreInvalidPath:false}
# Path to spec mapping. One or more base paths can map to the same specifications. The key is the base path and the value is the specification name.
# If users want to use multiple specification files in the same instance, each specification must have a unique base path and it must be set as key.
pathSpecMapping:
  /petstore: openapi-petstore
  /market: openapi-market

When using the above config file, you need to make sure that openapi-petstore.yaml and openapi-market.yaml will be in the same folder. In the pathSpecMapping, the key is the basePath which is a common prefix in the requests. This basePath will also be set to the individual helper basePath in case the basePath is not loaded properly from the specification file server section.

In the single specification case, the basePath will be resolved from the specification server section if possible. Otherwise, it will be overwritten by the basePath configuration property from handler.yml file. Please note that the basePath from handler.yml will only work for single specification.

  • About Light
    • Overview
    • Testimonials
    • What is Light
    • Features
    • Principles
    • Benefits
    • Roadmap
    • Community
    • Articles
    • Videos
    • License
    • Why Light Platform
  • Getting Started
    • Get Started Overview
    • Environment
    • Light Codegen Tool
    • Light Rest 4j
    • Light Tram 4j
    • Light Graphql 4j
    • Light Hybrid 4j
    • Light Eventuate 4j
    • Light Oauth2
    • Light Portal Service
    • Light Proxy Server
    • Light Router Server
    • Light Config Server
    • Light Saga 4j
    • Light Session 4j
    • Webserver
    • Websocket
    • Spring Boot Servlet
  • Architecture
    • Architecture Overview
    • API Category
    • API Gateway
    • Architecture Patterns
    • CQRS
    • Eco System
    • Event Sourcing
    • Fail Fast vs Fail Slow
    • Integration Patterns
    • JavaEE declining
    • Key Distribution
    • Microservices Architecture
    • Microservices Monitoring
    • Microservices Security
    • Microservices Traceability
    • Modular Monolith
    • Platform Ecosystem
    • Plugin Architecture
    • Scalability and Performance
    • Serverless
    • Service Collaboration
    • Service Mesh
    • SOA
    • Spring is bloated
    • Stages of API Adoption
    • Transaction Management
    • Microservices Cross-cutting Concerns Options
    • Service Mesh Plus
    • Service Discovery
  • Design
    • Design Overview
    • Design First vs Code First
    • Desgin Pattern
    • Service Evolution
    • Consumer Contract and Consumer Driven Contract
    • Handling Partial Failure
    • Idempotency
    • Server Life Cycle
    • Environment Segregation
    • Database
    • Decomposition Patterns
    • Http2
    • Test Driven
    • Multi-Tenancy
    • Why check token expiration
    • WebServices to Microservices
  • Cross-Cutting Concerns
    • Concerns Overview
  • API Styles
    • Light-4j for absolute performance
    • Style Overview
    • Distributed session on IMDG
    • Hybrid Serverless Modularized Monolithic
    • Kafka - Event Sourcing and CQRS
    • REST - Representational state transfer
    • Web Server with Light
    • Websocket with Light
    • Spring Boot Integration
    • Single Page Application
    • GraphQL - A query language for your API
    • Light IBM MQ
    • Light AWS Lambda
    • Chaos Monkey
  • Infrastructure Services
    • Service Overview
    • Light Proxy
    • Light Mesh
    • Light Router
    • Light Portal
    • Messaging Infrastructure
    • Centralized Logging
    • COVID-19
    • Light OAuth2
    • Metrics and Alerts
    • Config Server
    • Tokenization
    • Light Controller
  • Tool Chain
    • Tool Chain Overview
  • Utility Library
  • Service Consumer
    • Service Consumer
  • Development
    • Development Overview
  • Deployment
    • Deployment Overview
    • Frontend Backend
    • Linux Service
    • Windows Service
    • Install Eventuate on Windows
    • Secure API
    • Client vs light-router
    • Memory Limit
    • Deploy to Kubernetes
  • Benchmark
    • Benchmark Overview
  • Tutorial
    • Tutorial Overview
  • Troubleshooting
    • Troubleshoot
  • FAQ
    • FAQ Overview
  • Milestones
  • Contribute
    • Contribute to Light
    • Development
    • Documentation
    • Example
    • Tutorial
“Multiple Specifications” was last updated: December 11, 2022: fixes #352 add skipVerifyScopeWithoutSpec document (fa23dea)
Improve this page
  • News
  • Docs
  • Community
  • Reddit
  • GitHub
  • About Light
  • Getting Started
  • Architecture
  • Design
  • Cross-Cutting Concerns
  • API Styles
  • Infrastructure Services
  • Tool Chain
  • Utility Library
  • Service Consumer
  • Development
  • Deployment
  • Benchmark
  • Tutorial
  • Troubleshooting
  • FAQ
  • Milestones
  • Contribute