From ca4ef2fa835a94944e8107326291e1f0d91db3cc Mon Sep 17 00:00:00 2001 From: Tom Peltonen Date: Tue, 19 Sep 2023 21:12:38 +1000 Subject: [PATCH] Adding tutorial material --- README.md | 3 +- docs/README.md | 3 + docs/tutorial/message/README.md | 124 ++++++++++++++++++++++++++++++++ docs/tutorial/setup/README.md | 12 ++++ 4 files changed, 141 insertions(+), 1 deletion(-) create mode 100644 docs/README.md create mode 100644 docs/tutorial/message/README.md create mode 100644 docs/tutorial/setup/README.md diff --git a/README.md b/README.md index 8eb7a54..b0c1954 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ # qaskx.docs -This is the repository for public QaskX documentation \ No newline at end of file +This is the repository for public QaskX documentation + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b3a027d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# QASKX Documentation + + diff --git a/docs/tutorial/message/README.md b/docs/tutorial/message/README.md new file mode 100644 index 0000000..de0627a --- /dev/null +++ b/docs/tutorial/message/README.md @@ -0,0 +1,124 @@ +# 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. + diff --git a/docs/tutorial/setup/README.md b/docs/tutorial/setup/README.md new file mode 100644 index 0000000..975987a --- /dev/null +++ b/docs/tutorial/setup/README.md @@ -0,0 +1,12 @@ +# Setup Qaskx + +Before you can use and the get the benefits of **qaskx** you will +need to perform some initial tasks or setup. + +In summary for the tutorials here you will need: +* Donwload the **qaskx-cli** program which is a command line tool +* Have a development environment +* Optionally, installed Go lang for tutorials. +* Have access to Git +* Optionally, have Docker or Podman installed +