125 lines
3.6 KiB
Markdown
125 lines
3.6 KiB
Markdown
# 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](../setup/README.md) 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](message_openapi.json)
|
|
|
|
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](message_openapi.json)
|
|
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.
|
|
|