OpenAPI 3.0 Petstore

The petstore RESTful API is used by a lot of frameworks as reference application and in this tutorial, we will walk you through the steps to get petstore generated and then deployed to production. Within these steps, we will show you how to use the features of light-4j and light-rest-4j OpenAPI 3.0 support. If you are interested in light-rest-4j Swagger 2.0 support, please take a look at Swagger 2.0 Petstore Tutorial.

Please note that our frameworks are aimed towards microservices. There are several tutorials to showcase multiple services interacting with each other. These can be found at rest tutorial section. The public available petstore specification is designed as monolithic API.

Petstore is a generated RESTful API project based on OpenAPI 3.0 specification found here. After the project is generated, we will try to change the configuration to enable other features in following steps.

This tutorial shows how to use the service registry and discovery feature of light*4j frameworks.

Environment

You will need the following dependencies before starting this tutorial: Java JDK 11 (I prefer OpenJDK but Oracle JDK will do) Maven Git Docker The use of docker-compose is optional but can sometimes be problematic for Windows users. Assuming the above software packages are installed, we need to create a workspace and clone the projects needed for this tutorial. The following will assume your workspace is in a directory named networknt under your home directory. Read More »

Generate

We have built light-codegen to support project scaffolding for all the frameworks provided by the Light platform. We believe that in order to build scalable enterprise applications and microservices, you have to adopt a design first methodology. There are numerous ways to use light-codegen but for the purposes of this tutorial, we are using it as a command line tool. This project will be updated periodically when a new version of the light-4j framework is released or if any updates are made to light-codegen. Read More »

Build and Start

In the previous step, we’ve generated a project into light-example-4j/rest/openapi/petstore folder and it is ready to be built and started. The default build tool generated is Maven and we are planning to support Gradle soon so that users can choose their favorite tool from config.json for the light-codegen To build and start the generated server, use the following command: cd ~/networknt/light-example-4j/rest/openapi/petstore mvn install exec:exec Now the server is started and listens to port 8443 on HTTPS with HTTP 2. Read More »

Test

The best GUI tool to test a RESTful API is Postman and the best command line tool is curl. Postman makes it very easy to set headers and query parameters while being able to save the configuration for future usage. If you have a lot of endpoints, it is highly recommended to save all of them as a project so that these endpoints can be easily retrieved. Some people like the curl command line and it works as well. Read More »

Security

By default, the generated API has security turned off. You can turn on the JWT verification by updating src/main/resources/config/security.yml in petstore project. Here is the default security.yml # Security configuration in light framework. --- # Enable JWT verification flag. enableVerifyJwt: false # Enable JWT scope verification. Only valid when enableVerifyJwt is true. enableVerifyScope: true # User for test only. should be always be false on official environment. enableMockJwt: false # JWT signature public certificates. Read More »

Docker

When petstore is generated, a folder called docker with two default Dockerfiles were generated at the same time for any further customization. Also, there is a build.sh in the root folder that can be used to build and publish docker images. Here is the content of Dockerfile which uses alpine Linux as base image to get minimum size. FROM openjdk:8-jre-alpine #EXPOSE 8443 ADD /target/petstore-1.0.1.jar server.jar CMD ["/bin/sh","-c","java -Dlight-4j-config-dir=/config -Dlogback.configurationFile=/config/logback.xml -jar /server. Read More »

Metrics

In the previous steps, we have explored how to send logs to a centralized server so that activity across multiple services can be viewed on the same screen. In this step, we are going to set up metrics from the petstore to send it to InfluxDB and then subsequently viewed from Chronograf UI. To start InfluxDB, Chronograf and Kapacitor, a docker-compose file will be used from the light-docker repository. Now let’s start all services defined in the docker-compose-metrics. Read More »

Logging

Logging is very important in microservices architecture as logs must be aggregated in order to trace all the activities of a particular request from a consumer. We are using ELK stack for logging. In production in Kubernetes cluster, there are vary options for logging and we may replace Logstash with Fluentd. In this turorial, Elasticsearch, Logstash and Kibana are all started in the same docker-compose.yml. In order for the example-petstore container to forward log files to ELK, we need to set up log driver on the application container to forward logs to Logstash and then to ElasticSearch. Read More »

Summary

This concludes the OpenAPI petstore tutorial on the dev environment; however, the steps are not for production as there are a lot of security issues that need to be addressed and containers that won’t be managed by docker-compose on production. Kubernetes or Docker Swarm will be utilized likely. This is out of the scope for this tutorial for now. Under construction. Read More »

Compose

In the previous step, an individual docker container is started with all the config files default in the docker container. In this tutorial, we are going to create a docker-compose.yml file with externalized config files so that we can change the petstore behavior with the same container image. The externalized config file will be put into light-config-test repository and it contains most config files for vary projects in testing mode. Read More »