qaskx.docs/docs/tutorial/message/README.md

Application Message Tutorial

The objective of this tutorial is to demonstrate the use of qaskx to build a microservice to provide an application with messages to display in app.

The messages can be:**

• informational
• warning
• error

Let's Start

Pre-requisites

Before commencing with this tutorial, the following is assumed:

• Git installed
• Go language installed
• qaskx installed and setup
• Visual Studio Code installed

You can follow the Setup Tutorial to perform the pre-requisites.

Objective

The project objective is to create a microservice in Golang to provide messages to an application and along the way demonstrate the qaskx fatures by using qaskx-cli command line tool.

Note 1: The microservice is a read only service and there is no security implemented on its use. Data is added to the service by adding data files.

Note 2: This tutorial does not create a remote Github repository for the tutorial.

Establish project space

The command line tool qaskx-cli is assumed to be in your path, otherwise you will need to specify the full path location to the tool.

You can always get help for the command line tool by executing

qaskx-cli --help
qaskx-cli CMD SUB-CMD --help

where CMD is the command and SUB-CMD is the sub command.

Create the project folders and default files. All commands sample are assumed to be in the ~/projects/qaskx/messages unless otherwise stated

qaskx-cli generate project --name qaskx-messages --parent ~/projects/qaskx/messages --template template

cd ~/projects/qaskx/messages

Start the OpenAPI specification design using:

• Visual Studio Code OR
• Apicurtio (?) using Docker

Editing OpenAPI with Visual Studio Code

Using VS Code to edit the OpenAPI requires you to know the OpenAPI specification language. Visual renders of the OpenAPI is available in the VS Code marketplace (for example .... )

Open VS Code to folder ~/projects/qaskx/messages

Open the OpenAPI specification file specs/openapi.json and observe the base template definition.

As this tutorial is not about OpenAPI writing, the required OpenAPI has been pre-prepared for you. For this tutorial you can replace the contents of the OpenAPI file with the contents from file Message OpenAPI

After copying the contents to VS Code editor for the openapi.json file, observe the paths and data models.

Editing OpenAPI with Apicurito

Apicurtio requires less knowledge about the OpenAPI specification language because it provides a UI editor. With the editor you need define data models and then the service paths, which use the data models in requests and responses.

To edit the OpenAPI using Apicurtio:

• Start Docker if not started
• Execute command

docker container run ....

• Start browser session

http://localhost:8080

• Open the OpenAPI file at (or drop it on the Apicurito browser window)

~/projects/qaskx/messages/specs/openapi.json

• The OpenAPI already comes prefiled with some details

As this tutorial is not about OpenAPI writing, the required OpenAPI has been pre-prepared for you. For this tutorial you can replace the contents of the OpenAPI file with the contents from file Message OpenAPI by opening the source tab at the root of the definition.

After copying the contents to VS Code editor for the openapi.json file, observe the paths and data models.

Generating the server code

Compiling and running

Postman or Browser

You can test the micro service by using Postman or using a browser.