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. Read More »

In light-rest-4j, there is a specification module. It contains several handlers to render Swagger UI for light-rest-4j services including http-sidecar and light-gateway to assist users to test the API from the browser. Handlers SpecSwaggerUIHandler The main handler is called SpecSwaggerUIHandler and it will return an HTML file to render the Swagger UI. The HTML refers to a url for the OpenAPI specification file on the server as “/spec.yaml”. SpecDisplayHandler The /spec. Read More »

Several components are related to the REST API request/response validation, and they all serve different purposes. json-schema-validator json-schema-validator is a green library that is responsible for validating the JSON against the JSON schema. We are using it to validate the incoming request (headers, query parameters, path parameters and body) extracted from the OpenAPI specification. I am guessing this is the validator you are looking for. It can flatten the $ref, but it is during the runtime. Read More »

If you want upgrade your application manually to the latest version of light-rest-4j framework, please make sure that the versions match the ones from pom.xml. It is highly recommended to regenerate your application with the latest light-codegen and compare with you current application to leverage new features from the new release. Read More »

In the light-rest-4j framework, we have provided two handlers to display OpenAPI Specification for the service API. It only works with OpenAPI 3.0 specifications. OpenApi display Handler SpecDisplayHandler - Load specification content directly from the browser. As the OpenAPI 3.0 specification can be named as openapi.yaml, openapi.yml or openapi.json, And it can be located anywhere in different deployment environments. We have this handler to load the specification based on the specification. Read More »

Swagger 2.0 is the first release of the Swagger specification that is used to describe RESTful APIs. There are some gaps in the specification but the tool chain around this specification is the most mature. As OpenAPI 3.0 is new, most existing project are using Swagger 2.0 specification format. For brand new project, it is recommended using OpenAPI 3.0. There are some middleware handlers designed for Swagger 2.0 specification. Swagger 2. Read More »

OpenAPI 3.0 was released in mid 2017 and was supported until the end of 2017. The specification is not backward compatible to the previous Swagger 2.0 and the tool chain around this specification format is still lacking. We have to build our own openapi-parser in order to support it in light-rest-4j framework. There are some middleware handlers designed for OpenAPI 3.0 specification. OpenAPI 3.0 Specific Handlers openapi-meta loads the openapi. Read More »

This handler is part of the light-rest-4j which is built on top of light-4j but focused on RESTful API only. Also, it only works with the OpenAPI 3.0 specification. Light-4j encourages design driven implementation so OpenAPI specification should be done before the implementation starts. With the light-codegen generator, the server stub can be generated and start running within seconds. However, we cannot rely on the generator for validation as specification will be changed along the life cycle of the API. Read More »

This module is part of light-rest-4j, built on top of light-4j but focused on RESTful API security only. It only works with the OpenAPI 3.0 specification. The JwtVerifyHandler supports OAuth2 with JWT token distributed verification and can be extended to other authentication and authorization approaches with UnifiedSecurityHandler. JwtVerifyHandler This is the handler that is injected during server startup if security.yml enableVerifyJwt is true. It does further scope verification if enableVerifyScope is true against OpenAPI specification. Read More »

This handler is part of light-rest-4j which is built on top of light-4j but is focused on RESTful API only. It only works with the OpenAPI 3.0 specification. It is designed based on the OpenAPI specification, so it is our best interest to utilize the openapi.yaml or openapi.json to its full potential. Currently, two components are using the OpenAPI specification during runtime. openapi-security - Verifies scopes in the JWT token against the scopes defined in OpenAPI specification if scope verification is true. Read More »

This handler is part of the light-rest-4j which is built on top of light-4j but focused on RESTful API only. Also, it only works with Swagger 2.0 specification. Light-4j encourages design driven implementation so Swagger specification should be done before the implementation starts. With the light-codegen generator, the server stub can be generated and start running within seconds. However, we cannot rely on the generator for validation as specification will be changed along the life cycle of the API. Read More »

This handler is part of the light-rest-4j which is built on top of light-4j but focused on RESTful API only. Also, it only works with Swagger 2.0 specification. It supports OAuth2 with JWT token distributed verification and can be extended to other authentication and authorization approaches. JwtVerifyHandler This is the handler that is injected during server start up if security.yml enableVerifyJwt is true. It does further scope verification if enableVerifyScope is true against swagger specification. Read More »

This handler is part of the light-rest-4j which is built on top of light-4j but focused on RESTful API only. Also, it only works with Swagger 2.0 specification. It is designed based on swagger specification so it is our best interest to utilize the swagger.json to its full potential. Currently there are two components are using the swagger specification during runtime. swagger-security - Verify scope in the JWT token against scope defined in swagger specification if scope verification is true. Read More »

There are so many tools that help us to build restful microservices and here is a small list we use very often. Swagger Editor/tool/swagger-editor/) is used to create and update swagger specifications. Swagger CLI to validate, merge and convert swagger specification files. OpenAPI Parser to parse and validate OpenAPI 3.0 specification file in both JSON and YAML formats. Swagger Bundler to merge multiple files specification into one self-contained JSON with all $ref resolved locally. Read More »

There are two set of middleware handlers or plugins available to support Swagger 2.0 specification and OpenAPI 3.0 specification. For handlers for Swagger 2.0, they are prefixed with “swagger-” and for handlers designed for OpenAPI 3.0, they are prefixed with “openapi-”. Middleware Handlers for OpenAPI 3.0 openapi-meta loads the OpenAPI 3.0 openapi.json and split it to operation level so that it can be looked up when the request comes in. Read More »

As light-rest-4j is the first framework supported, we have more Restful examples than any other style of microservices. All rest examples can be found at light-example-4j. Under the rest folder there are two folders to differentiate Swagger 2.0 and OpenAPI 3.0 implementations. If you are interested in implementing your Restful services in Kotlin, you can find examples in light-example-kotlin repository openapi folder. As we are encouraging the design-driven approach to build services, you can find the corresponding specifications for these examples as well as light-codegen config files in the model-config repository. Read More »