From 940bc1931d9c569458c3a5d864085c3100eafacb Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Sun, 23 Jul 2023 13:55:22 +1000 Subject: [PATCH 01/10] Starting docs with deve Quickstart --- docs/developers/quickstart.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/developers/quickstart.md diff --git a/docs/developers/quickstart.md b/docs/developers/quickstart.md new file mode 100644 index 0000000..28c3cf5 --- /dev/null +++ b/docs/developers/quickstart.md @@ -0,0 +1,25 @@ +## Quickstart for developers + + +```mermaid + +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant git as Github + + dev ->>+ vsc: start IDE + Note right of vsc: Existing Git project + + vsc ->>+ git : + Note right of vsc: Clone existing git for project + git -->>- vsc : Cloned + + + + vsc -->>- dev : complete + + +``` + From 80e8fdc9ab1a7f38742b35e18f7be2e2d1f636b5 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Sun, 23 Jul 2023 21:45:31 +1000 Subject: [PATCH 02/10] Created various flow documents --- background.md | 9 +- docs/analysis_start.md | 88 +++++++++++++++ docs/developer_update.md | 22 ++++ docs/developers/quickstart.md | 25 ----- docs/developers_client_start.md | 187 ++++++++++++++++++++++++++++++++ docs/developers_server_start.md | 185 +++++++++++++++++++++++++++++++ docs/project_start.md | 21 ++++ 7 files changed, 505 insertions(+), 32 deletions(-) create mode 100644 docs/analysis_start.md create mode 100644 docs/developer_update.md delete mode 100644 docs/developers/quickstart.md create mode 100644 docs/developers_client_start.md create mode 100644 docs/developers_server_start.md create mode 100644 docs/project_start.md diff --git a/background.md b/background.md index 9cd5bac..0a21d5b 100644 --- a/background.md +++ b/background.md @@ -1,9 +1,4 @@ +# Background +_This document is under construction_ - -```mermaid - -mindmaps - - -``` diff --git a/docs/analysis_start.md b/docs/analysis_start.md new file mode 100644 index 0000000..990c5c4 --- /dev/null +++ b/docs/analysis_start.md @@ -0,0 +1,88 @@ +# Analysis flow (start) + + +The assumptions for this documents are: + +* the Git repository has been created and contains little content +* a new API is required to be exposed +* no OpenAPI definition exists +* no API coding has commenced +* ApiCurio is the OpenAPI editor, and this has been linked to GitHub + +It is beneficial if the objectives for the API and its high level +service domain scope have already been agreed before starting +to define the API. + +Knowing the information to fetch or tasks that need to be performed +will assist in comleting the API specification. This information +could be captured in the API specification so as to avoid duplciate +sources of information that needs to be synchronised. + +Information in the OpenAPI specification can be extracted and rendered +into various formats, such as CSV lists of fields, their types, +size and description. + +## Sequence Diagram + +```mermaid + +sequenceDiagram + + actor ba as Business Analyst + participant ide as ApiCurio + participant git as Github + participant oas3f as OpenAPI file + + Note over git, oas3f: The OpenAPI file is stored in Git + + ba ->>+ ide: start IDE + + ide ->> ide: Create new API + Note over ba, oas3f: New API is to meet naming standards for services + ide ->> ide: Create new data structures + Note over ba, oas3f: Data structures include requests and responses + ide ->> ide: Create new paths and methods + Note over ba, oas3f: Includes non 200 response handling, headers and security + + ide ->>+ git: Commit to git + git ->>+ oas3f: OpenAPI file under Git + oas3f -->>- git: Saved + git --) git: Trigger GitActions for lint + git -->>- ide: + + ide -->>- ba: close + +``` + +When creating the OpenAPI specification the information to include: +* Summary and abtstract +* Version +* Descriptions for fields +* Field attributes including mandatory, type, enumeration and rules such as size +* Descriptions for paths + +A lint process will be run over the OpenAPI specification to ensure adherence +to styling standards. + +# End Status of flow + +At the end of this flow the OpenAPI (and/or AsyncAPI) specification will +be in a stable state so that coding can commence. Minor changes to the +specification can still occur, and completely new paths can be added. + +When the specification changes the version will change according +to semantic versioning rules. + +The OpenAPI definition generated is next used in the +[developer client start](developers_client_start.md) or +[developer server start](developers_server_start.md) flow. + +The client will need to consume a mock service until the +server code is built. + +# Reading Notes + +The ApiCurio and Github components can be substitued for +other software products uch as Swagger Editor and Bitbucket +that provide similar capabilities. + diff --git a/docs/developer_update.md b/docs/developer_update.md new file mode 100644 index 0000000..66788f6 --- /dev/null +++ b/docs/developer_update.md @@ -0,0 +1,22 @@ +# Developer update flow + +_This document is intended to cover the scenario where the **rediops** +contents change including references to OpenAPI specifications._ + +_This document under construction._ + + +# End Status of flow + +At the end of this flow the code has been updated with latest +definitions. + +# Reading Notes + +Using code generators will break the code in many situations and +therefore using Git and diff tools will help in identifying +what has changed and perform impact analysis. + +In many situations with specification changes the compiler +will pick up the changes. Some changes can only be detected +at run time if there is a high level of abstraction. diff --git a/docs/developers/quickstart.md b/docs/developers/quickstart.md deleted file mode 100644 index 28c3cf5..0000000 --- a/docs/developers/quickstart.md +++ /dev/null @@ -1,25 +0,0 @@ -## Quickstart for developers - - -```mermaid - -sequenceDiagram - - actor dev as Developer - participant vsc as Visual Studio Code - participant git as Github - - dev ->>+ vsc: start IDE - Note right of vsc: Existing Git project - - vsc ->>+ git : - Note right of vsc: Clone existing git for project - git -->>- vsc : Cloned - - - - vsc -->>- dev : complete - - -``` - diff --git a/docs/developers_client_start.md b/docs/developers_client_start.md new file mode 100644 index 0000000..87373c0 --- /dev/null +++ b/docs/developers_client_start.md @@ -0,0 +1,187 @@ +# Front end client developer flow (start) + +This is the initialisation of the front end +client code. Coding the server is covered in document +[developers server start](developers_server_start.md) + +The [analysis start](analysis_start.md) is a pre-requisite for +this flow. + +The assumptions for this documents are: + +* the Git repository has been created +* a new API is required to be exposed +* an OpenAPI definition exists in Git +* no API coding has commenced +* Visual Studio Code has been installed +* Developer has access to the API editor viewer for the OpenAPI specification + +## Sequence Diagram + +### Automation + +The sequence of automation activity using **rediops** and **qaskx-cli** is +as follows. + +The Qaskx command line tool needs to be installed on the developer machine + +```mermaid + +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant term as Terminal + participant qaskx as qaskx-cli + participant cmdb as CMDB + participant git as Github + link git: GitHub @ https://github.com/meerkat-manor/rediOps + participant oas3f as OpenAPI file + participant rediops as rediops file + participant apip as API portal + + dev ->>+ vsc: start IDE + + Note over vsc, term: Clone existing git for project + vsc ->>+ git : + git -->>- vsc : Cloned, project opened + + Note over git, rediops: The OpenAPI and redops files are stored in Git + + vsc ->>+ term: start + term ->>+ qaskx: New CI + qaskx ->>+ rediops: Read + rediops -->>- qaskx: Contents + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + Note over cmdb, git: qaskx rediops ci cmd + qaskx ->>+ cmdb: + cmdb -->>- qaskx: New CI value + qaskx -) rediops: Update CI entry + qaskx -->>- term: Success + + term ->>+ qaskx: Generate code + Note over qaskx, cmdb: qaskx gen client cmd + qaskx ->>+ rediops: Read + rediops -->>- qaskx: Contents + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + qaskx -) qaskx: Auto generate client code + qaskx -) qaskx: Auto generate sequence diagram + qaskx -) qaskx: Auto generate gateway infra + qaskx -) qaskx: Auto generate feature flags + qaskx -) rediops: Auto update entries, including build, test + qaskx -->>- term: Success + + alt Regsiter API if not already done + + term ->>+ qaskx: Register API + Note over cmdb, git: qaskx rediops register cmd + qaskx ->>+ rediops: Read + rediops -->>- qaskx: Contents + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + qaskx ->>+ apip: + apip -->>- qaskx: Registered + qaskx -) rediops: Auto update API entry + qaskx -->>- term: Success + + end + + term -->- vsc: close + + vsc ->>+ git: Commit + git --) git: Trigger GitActions for lint, gateway, features, etc + git ->>- vsc: Success + + vsc -->>- dev: close + +``` + +### Manual + +The equivalent sequence of manual activity, non qaskx actions is as follows. +The **rediops** file is still used. Without **rediops** file you will +follow whatever your existing process is and recorded the necessary +details in various documents + +The OpenAPI tool needs to be installed on the developer machine. + +```mermaid + +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant cmdb as CMDB + link vsc: Visual Studio @ https://code.visualstudio.com/ + participant term as Terminal + participant git as Github + link git: GitHub @ https://github.com/meerkat-manor/rediOps + participant oas3f as OpenAPI file + participant rediops as rediops file + participant oas3 as OpenAPI tool + participant apip as API portal + + + Note over cmdb, vsc: Create new CI entry for Client + dev ->>+ cmdb: Access UI + cmdb -->> cmdb: Create CI entry + cmdb -->>- dev: Close, noting CI value + + Note over git, rediops: The rediops file is stored in Git + + dev ->>+ vsc: start IDE + + Note over cmdb, vsc: Clone existing git for project + vsc ->>+ git : + git -->>- vsc : Cloned, project opened + + vsc -) rediops: Update CI entry + + vsc ->>+ term: start + Note over git, oas3: Set generation parameters + term ->>+ oas3: Generate code cmd + oas3 ->>+ oas3f: Read + oas3f -->>- oas3: Contents + oas3 -->>- term: Success + term -->- vsc: close + + vsc -) vsc: Update client code with defaults + vsc -) vsc: Manually write sequence diagrams + vsc -) vsc: Manually write Gateway infra + vsc -) vsc: Manually write feature flags + + alt Regsiter API if not already done + + dev ->>+ apip: Register API + apip -->>- dev: Registered + + end + + vsc -) rediops: Manually update entries + + vsc ->>+ git: Commit + git --) git: Trigger GitActions for lint, gateway, features, etc + git ->>- vsc: Success + + vsc -->>- dev: Done + + +``` + +# End Status of flow + +At the end of this flow the basic code stubs exist and have been committed +to Github. The code can execute and will return not implemented +response results if the client is a non UI, headless consumer of the API. + +For clients that will have a UI, the code will not work as no UI coding is +expected to have been done. + + +# Reading Notes + +The Visual Studio Code, CMDB and Github components can be substitued for +other software products such IntelliJ and Bitbucket. + diff --git a/docs/developers_server_start.md b/docs/developers_server_start.md new file mode 100644 index 0000000..70189cb --- /dev/null +++ b/docs/developers_server_start.md @@ -0,0 +1,185 @@ +# Back end server developer flow (start) + +This is the initialisation of the back end +code. Coding the client is covered in document +[developers client start](developers_client_start.md) + +The [analysis start](analysis_start.md) is a pre-requisite for +this flow. + +The assumptions for this documents are: + +* the Git repository has been created +* a new API is required to be exposed +* an OpenAPI definition exists in Git +* no API coding has commenced +* Visual Studio Code has been installed +* Developer has access to the API editor viewer for the OpenAPI specification + + +## Sequence Diagram + +### Automation + +The sequence of automation activity using **rediops** and **qaskx-cli** is +as follows. + +The Qaskx command line tool needs to be installed on the developer machine + +```mermaid + +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant term as Terminal + participant qaskx as qaskx-cli + participant cmdb as CMDB + participant git as Github + link git: GitHub @ https://github.com/meerkat-manor/rediOps + participant oas3f as OpenAPI file + participant rediops as rediops file + participant apip as API portal + + dev ->>+ vsc: start IDE + + Note over vsc, term: Clone existing git for project + vsc ->>+ git : + git -->>- vsc : Cloned, project opened + + Note over git, rediops: The OpenAPI and rediops files are stored in Git + + vsc ->>+ term: start + term ->>+ qaskx: New CI + qaskx ->>+ rediops: Read + rediops -->>- qaskx: Contents + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + Note over cmdb, git: qaskx rediops ci cmd + qaskx ->>+ cmdb: + cmdb -->>- qaskx: New CI value + qaskx -) rediops: Update CI entry + qaskx -->>- term: Success + + term ->>+ qaskx: Generate code + Note over qaskx, cmdb: qaskx gen server cmd + qaskx ->>+ rediops: Read + rediops -->>- qaskx: Contents + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + qaskx -) qaskx: Auto generate server code + qaskx -) qaskx: Auto generate sequence diagram + qaskx -) qaskx: Auto generate gateway infra + qaskx -) qaskx: Auto generate feature flags + qaskx -) rediops: Auto update entries, including build, test + qaskx -->>- term: Success + + alt Regsiter API if not already done + + term ->>+ qaskx: Register API + Note over cmdb, git: qaskx rediops register cmd + qaskx ->>+ rediops: Read + rediops -->>- qaskx: Contents + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + qaskx ->>+ apip: + apip -->>- qaskx: Registered + qaskx -) rediops: Auto update API entry + qaskx -->>- term: Success + + end + + term -->- vsc: close + + vsc ->>+ git: Commit + git --) git: Trigger GitActions for lint, gateway, features, etc + git ->>- vsc: Success + + vsc -->>- dev: close + +``` + +### Manual + +The equivalent sequence of manual activity, non qaskx actions is as follows. +The **rediops** file is still used. Without **rediops** file you will +follow whatever your existing process is and recorded the necessary +details in various documents + +The OpenAPI tool needs to be installed on the developer machine. + +```mermaid + +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant cmdb as CMDB + link vsc: Visual Studio @ https://code.visualstudio.com/ + participant term as Terminal + participant git as Github + link git: GitHub @ https://github.com/meerkat-manor/rediOps + participant oas3f as OpenAPI file + participant rediops as rediops file + participant oas3 as OpenAPI tool + participant apip as API portal + + + Note over cmdb, vsc: Create new CI entry for API + dev ->>+ cmdb: Access UI + cmdb -->> cmdb: Create CI entry + cmdb -->>- dev: Close, noting CI value + + Note over git, rediops: The OpenAPI and redops files are stored in Git + + dev ->>+ vsc: start IDE + + Note over cmdb, vsc: Clone existing git for project + vsc ->>+ git : + git -->>- vsc : Cloned, project opened + + vsc -) rediops: Update CI entry + + vsc ->>+ term: start + Note over git, oas3: Set generation parameters + term ->>+ oas3: Generate code cmd + oas3 ->>+ oas3f: Read + oas3f -->>- oas3: Contents + oas3 -->>- term: Success + term -->- vsc: close + + vsc -) vsc: Update server code with defaults + vsc -) vsc: Manually write sequence diagrams + vsc -) vsc: Manually write Gateway infra + vsc -) vsc: Manually write feature flags + + alt Regsiter API if not already done + + dev ->>+ apip: Register API + apip -->>- dev: Registered + + end + + vsc -) rediops: Manually update entries + + vsc ->>+ git: Commit + git --) git: Trigger GitActions for lint, gateway, features, etc + git ->>- vsc: Success + + vsc -->>- dev: Done + + +``` + +# End Status of flow + +At the end of this flow the basic code stubs exist and have been committed +to Github. The code can execute and will return not implemented +response results. + + +# Reading Notes + +The Visual Studio Code, CMDB and Github components can be substitued for +other software products such IntelliJ and Bitbucket. + diff --git a/docs/project_start.md b/docs/project_start.md new file mode 100644 index 0000000..f332f3f --- /dev/null +++ b/docs/project_start.md @@ -0,0 +1,21 @@ +# Project flow + +_This document under construction._ + + +# End Status of flow + +At the end of this flow the scope of the API delivery and the service domain +will be understood. + +The project information is next used in the +[analysis start](analysis_start.md) flow. + +# Reading Notes + +A well defined service domain that is understood and agreed by all parties +will reduce rework effort, though with automation tools the manual effort +can be better managed. + +A service domain can only return information or action requests that are +within its ability to fetch or remit to complete. From c8a71c9be50d5ddd86df1e85e6202fbfbab9cce3 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Sun, 23 Jul 2023 21:57:08 +1000 Subject: [PATCH 03/10] Spelling corrections --- .vscode/settings.json | 12 +++++++++ docs/analysis_start.md | 8 +++--- docs/developer_update.md | 4 +-- docs/developers_client_start.md | 48 ++++++++++++++++----------------- docs/developers_server_start.md | 48 ++++++++++++++++----------------- 5 files changed, 66 insertions(+), 54 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..b684aed --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,12 @@ +{ + "cSpell.words": [ + "cmdb", + "initialisation", + "Qaskx", + "rediops", + "synchronised" + ], + "cSpell.ignoreWords": [ + "apip" + ] +} \ No newline at end of file diff --git a/docs/analysis_start.md b/docs/analysis_start.md index 990c5c4..5405dfe 100644 --- a/docs/analysis_start.md +++ b/docs/analysis_start.md @@ -14,8 +14,8 @@ service domain scope have already been agreed before starting to define the API. Knowing the information to fetch or tasks that need to be performed -will assist in comleting the API specification. This information -could be captured in the API specification so as to avoid duplciate +will assist in completing the API specification. This information +could be captured in the API specification so as to avoid duplicate sources of information that needs to be synchronised. Information in the OpenAPI specification can be extracted and rendered @@ -55,7 +55,7 @@ sequenceDiagram ``` When creating the OpenAPI specification the information to include: -* Summary and abtstract +* Summary and abstract * Version * Descriptions for fields * Field attributes including mandatory, type, enumeration and rules such as size @@ -82,7 +82,7 @@ server code is built. # Reading Notes -The ApiCurio and Github components can be substitued for +The ApiCurio and Github components can be substituted for other software products uch as Swagger Editor and Bitbucket that provide similar capabilities. diff --git a/docs/developer_update.md b/docs/developer_update.md index 66788f6..7d3b69a 100644 --- a/docs/developer_update.md +++ b/docs/developer_update.md @@ -1,7 +1,7 @@ # Developer update flow -_This document is intended to cover the scenario where the **rediops** -contents change including references to OpenAPI specifications._ +_This document is intended to cover the scenario where the **devops** +file contents change including references to OpenAPI specifications._ _This document under construction._ diff --git a/docs/developers_client_start.md b/docs/developers_client_start.md index 87373c0..5c84c94 100644 --- a/docs/developers_client_start.md +++ b/docs/developers_client_start.md @@ -20,7 +20,7 @@ The assumptions for this documents are: ### Automation -The sequence of automation activity using **rediops** and **qaskx-cli** is +The sequence of automation activity using **devops** file and **qaskx-cli** is as follows. The Qaskx command line tool needs to be installed on the developer machine @@ -35,9 +35,9 @@ sequenceDiagram participant qaskx as qaskx-cli participant cmdb as CMDB participant git as Github - link git: GitHub @ https://github.com/meerkat-manor/rediOps + link git: GitHub @ https://github.com/meerkat-manor/devops participant oas3f as OpenAPI file - participant rediops as rediops file + participant devops as devops file participant apip as API portal dev ->>+ vsc: start IDE @@ -46,44 +46,44 @@ sequenceDiagram vsc ->>+ git : git -->>- vsc : Cloned, project opened - Note over git, rediops: The OpenAPI and redops files are stored in Git + Note over git, devops: The OpenAPI and devops files are stored in Git vsc ->>+ term: start term ->>+ qaskx: New CI - qaskx ->>+ rediops: Read - rediops -->>- qaskx: Contents + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents - Note over cmdb, git: qaskx rediops ci cmd + Note over cmdb, git: qaskx devops ci cmd qaskx ->>+ cmdb: cmdb -->>- qaskx: New CI value - qaskx -) rediops: Update CI entry + qaskx -) devops: Update CI entry qaskx -->>- term: Success term ->>+ qaskx: Generate code Note over qaskx, cmdb: qaskx gen client cmd - qaskx ->>+ rediops: Read - rediops -->>- qaskx: Contents + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents qaskx -) qaskx: Auto generate client code qaskx -) qaskx: Auto generate sequence diagram qaskx -) qaskx: Auto generate gateway infra qaskx -) qaskx: Auto generate feature flags - qaskx -) rediops: Auto update entries, including build, test + qaskx -) devops: Auto update entries, including build, test qaskx -->>- term: Success - alt Regsiter API if not already done + alt Register API if not already done term ->>+ qaskx: Register API - Note over cmdb, git: qaskx rediops register cmd - qaskx ->>+ rediops: Read - rediops -->>- qaskx: Contents + Note over cmdb, git: qaskx devops register cmd + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents qaskx ->>+ apip: apip -->>- qaskx: Registered - qaskx -) rediops: Auto update API entry + qaskx -) devops: Auto update API entry qaskx -->>- term: Success end @@ -101,7 +101,7 @@ sequenceDiagram ### Manual The equivalent sequence of manual activity, non qaskx actions is as follows. -The **rediops** file is still used. Without **rediops** file you will +The **devops** file is still used. Without **devops** file you will follow whatever your existing process is and recorded the necessary details in various documents @@ -117,9 +117,9 @@ sequenceDiagram link vsc: Visual Studio @ https://code.visualstudio.com/ participant term as Terminal participant git as Github - link git: GitHub @ https://github.com/meerkat-manor/rediOps + link git: GitHub @ https://github.com/meerkat-manor/devops participant oas3f as OpenAPI file - participant rediops as rediops file + participant devops as devops file participant oas3 as OpenAPI tool participant apip as API portal @@ -129,7 +129,7 @@ sequenceDiagram cmdb -->> cmdb: Create CI entry cmdb -->>- dev: Close, noting CI value - Note over git, rediops: The rediops file is stored in Git + Note over git, devops: The devops file is stored in Git dev ->>+ vsc: start IDE @@ -137,7 +137,7 @@ sequenceDiagram vsc ->>+ git : git -->>- vsc : Cloned, project opened - vsc -) rediops: Update CI entry + vsc -) devops: Update CI entry vsc ->>+ term: start Note over git, oas3: Set generation parameters @@ -152,14 +152,14 @@ sequenceDiagram vsc -) vsc: Manually write Gateway infra vsc -) vsc: Manually write feature flags - alt Regsiter API if not already done + alt Register API if not already done dev ->>+ apip: Register API apip -->>- dev: Registered end - vsc -) rediops: Manually update entries + vsc -) devops: Manually update entries vsc ->>+ git: Commit git --) git: Trigger GitActions for lint, gateway, features, etc @@ -182,6 +182,6 @@ expected to have been done. # Reading Notes -The Visual Studio Code, CMDB and Github components can be substitued for +The Visual Studio Code, CMDB and Github components can be substituted for other software products such IntelliJ and Bitbucket. diff --git a/docs/developers_server_start.md b/docs/developers_server_start.md index 70189cb..1116200 100644 --- a/docs/developers_server_start.md +++ b/docs/developers_server_start.md @@ -21,7 +21,7 @@ The assumptions for this documents are: ### Automation -The sequence of automation activity using **rediops** and **qaskx-cli** is +The sequence of automation activity using **devops** file and **qaskx-cli** is as follows. The Qaskx command line tool needs to be installed on the developer machine @@ -36,9 +36,9 @@ sequenceDiagram participant qaskx as qaskx-cli participant cmdb as CMDB participant git as Github - link git: GitHub @ https://github.com/meerkat-manor/rediOps + link git: GitHub @ https://github.com/meerkat-manor/devops participant oas3f as OpenAPI file - participant rediops as rediops file + participant devops as devops file participant apip as API portal dev ->>+ vsc: start IDE @@ -47,44 +47,44 @@ sequenceDiagram vsc ->>+ git : git -->>- vsc : Cloned, project opened - Note over git, rediops: The OpenAPI and rediops files are stored in Git + Note over git, devops: The OpenAPI and devops files are stored in Git vsc ->>+ term: start term ->>+ qaskx: New CI - qaskx ->>+ rediops: Read - rediops -->>- qaskx: Contents + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents - Note over cmdb, git: qaskx rediops ci cmd + Note over cmdb, git: qaskx devops ci cmd qaskx ->>+ cmdb: cmdb -->>- qaskx: New CI value - qaskx -) rediops: Update CI entry + qaskx -) devops: Update CI entry qaskx -->>- term: Success term ->>+ qaskx: Generate code Note over qaskx, cmdb: qaskx gen server cmd - qaskx ->>+ rediops: Read - rediops -->>- qaskx: Contents + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents qaskx -) qaskx: Auto generate server code qaskx -) qaskx: Auto generate sequence diagram qaskx -) qaskx: Auto generate gateway infra qaskx -) qaskx: Auto generate feature flags - qaskx -) rediops: Auto update entries, including build, test + qaskx -) devops: Auto update entries, including build, test qaskx -->>- term: Success - alt Regsiter API if not already done + alt Register API if not already done term ->>+ qaskx: Register API - Note over cmdb, git: qaskx rediops register cmd - qaskx ->>+ rediops: Read - rediops -->>- qaskx: Contents + Note over cmdb, git: qaskx devops register cmd + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents qaskx ->>+ apip: apip -->>- qaskx: Registered - qaskx -) rediops: Auto update API entry + qaskx -) devops: Auto update API entry qaskx -->>- term: Success end @@ -102,7 +102,7 @@ sequenceDiagram ### Manual The equivalent sequence of manual activity, non qaskx actions is as follows. -The **rediops** file is still used. Without **rediops** file you will +The **devops** file is still used. Without **devops** file you will follow whatever your existing process is and recorded the necessary details in various documents @@ -118,9 +118,9 @@ sequenceDiagram link vsc: Visual Studio @ https://code.visualstudio.com/ participant term as Terminal participant git as Github - link git: GitHub @ https://github.com/meerkat-manor/rediOps + link git: GitHub @ https://github.com/meerkat-manor/devops participant oas3f as OpenAPI file - participant rediops as rediops file + participant devops as devops file participant oas3 as OpenAPI tool participant apip as API portal @@ -130,7 +130,7 @@ sequenceDiagram cmdb -->> cmdb: Create CI entry cmdb -->>- dev: Close, noting CI value - Note over git, rediops: The OpenAPI and redops files are stored in Git + Note over git, devops: The OpenAPI and devops files are stored in Git dev ->>+ vsc: start IDE @@ -138,7 +138,7 @@ sequenceDiagram vsc ->>+ git : git -->>- vsc : Cloned, project opened - vsc -) rediops: Update CI entry + vsc -) devops: Update CI entry vsc ->>+ term: start Note over git, oas3: Set generation parameters @@ -153,14 +153,14 @@ sequenceDiagram vsc -) vsc: Manually write Gateway infra vsc -) vsc: Manually write feature flags - alt Regsiter API if not already done + alt Register API if not already done dev ->>+ apip: Register API apip -->>- dev: Registered end - vsc -) rediops: Manually update entries + vsc -) devops: Manually update entries vsc ->>+ git: Commit git --) git: Trigger GitActions for lint, gateway, features, etc @@ -180,6 +180,6 @@ response results. # Reading Notes -The Visual Studio Code, CMDB and Github components can be substitued for +The Visual Studio Code, CMDB and Github components can be substituted for other software products such IntelliJ and Bitbucket. From 2b1b52cc2d5a597d39173c72f79ea7f373a26c20 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Sun, 23 Jul 2023 22:19:27 +1000 Subject: [PATCH 04/10] Corrected API dependency handling Added automation for OpenAPI scan --- docs/developers_client_start.md | 30 +++++++++++++++++++++--------- docs/developers_server_start.md | 20 ++++++++++++++++++++ 2 files changed, 41 insertions(+), 9 deletions(-) diff --git a/docs/developers_client_start.md b/docs/developers_client_start.md index 5c84c94..1d076af 100644 --- a/docs/developers_client_start.md +++ b/docs/developers_client_start.md @@ -48,12 +48,18 @@ sequenceDiagram Note over git, devops: The OpenAPI and devops files are stored in Git + alt If no OpenAPI dependency linked + vsc -) devops: Update OpenAPI dependency entry + end + vsc ->>+ term: start term ->>+ qaskx: New CI qaskx ->>+ devops: Read devops -->>- qaskx: Contents - qaskx ->>+ oas3f: Read + loop Read called dependencies + qaskx ->>+ oas3f: Read dependency oas3f -->>- qaskx: Contents + end Note over cmdb, git: qaskx devops ci cmd qaskx ->>+ cmdb: cmdb -->>- qaskx: New CI value @@ -62,27 +68,30 @@ sequenceDiagram term ->>+ qaskx: Generate code Note over qaskx, cmdb: qaskx gen client cmd - qaskx ->>+ devops: Read + qaskx ->>+ devops: Read dependency list devops -->>- qaskx: Contents - qaskx ->>+ oas3f: Read + loop Read called dependencies + qaskx ->>+ oas3f: Read dependency oas3f -->>- qaskx: Contents qaskx -) qaskx: Auto generate client code + end qaskx -) qaskx: Auto generate sequence diagram - qaskx -) qaskx: Auto generate gateway infra qaskx -) qaskx: Auto generate feature flags qaskx -) devops: Auto update entries, including build, test qaskx -->>- term: Success - alt Register API if not already done + alt Register using API dependencies if not already done - term ->>+ qaskx: Register API + term ->>+ qaskx: Register API dependencies Note over cmdb, git: qaskx devops register cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents + loop Read called dependencies qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents qaskx ->>+ apip: - apip -->>- qaskx: Registered + apip -->>- qaskx: Registered as consumer + end qaskx -) devops: Auto update API entry qaskx -->>- term: Success @@ -152,9 +161,9 @@ sequenceDiagram vsc -) vsc: Manually write Gateway infra vsc -) vsc: Manually write feature flags - alt Register API if not already done + alt Register using API dependencies if not already done - dev ->>+ apip: Register API + dev ->>+ apip: Register as consuming APIs apip -->>- dev: Registered end @@ -182,6 +191,9 @@ expected to have been done. # Reading Notes +For automation, some activities can be performed by GitActions calling +qaskx-cli. + The Visual Studio Code, CMDB and Github components can be substituted for other software products such IntelliJ and Bitbucket. diff --git a/docs/developers_server_start.md b/docs/developers_server_start.md index 1116200..f7ca3a1 100644 --- a/docs/developers_server_start.md +++ b/docs/developers_server_start.md @@ -53,6 +53,14 @@ sequenceDiagram term ->>+ qaskx: New CI qaskx ->>+ devops: Read devops -->>- qaskx: Contents + + alt If no OpenAPI linked + qaskx ->>+ git: + Note over oas3f, devops: Scan for OpenAPI file in Git + git -->>- qaskx: + qaskx -) devops: Update OpenAPI entry + end + qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents Note over cmdb, git: qaskx devops ci cmd @@ -65,6 +73,14 @@ sequenceDiagram Note over qaskx, cmdb: qaskx gen server cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents + + alt If no OpenAPI linked + qaskx ->>+ git: + Note over oas3f, devops: Scan for OpenAPI file in Git + git -->>- qaskx: + qaskx -) devops: Update OpenAPI entry + end + qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents qaskx -) qaskx: Auto generate server code @@ -140,6 +156,10 @@ sequenceDiagram vsc -) devops: Update CI entry + alt If no OpenAPI linked + vsc -) devops: Update OpenAPI entry + end + vsc ->>+ term: start Note over git, oas3: Set generation parameters term ->>+ oas3: Generate code cmd From 19f52c2d3d836a66da15350198e97eee136812d9 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Tue, 1 Aug 2023 23:46:54 +1000 Subject: [PATCH 05/10] Adding documentation --- docs/analysis_start.md | 8 +++- ...ent_start.md => developer_client_start.md} | 6 +-- ...ver_start.md => developer_server_start.md} | 9 ++++- docs/readme.md | 22 +++++++++++ docs/setup.md | 39 +++++++++++++++++++ 5 files changed, 77 insertions(+), 7 deletions(-) rename docs/{developers_client_start.md => developer_client_start.md} (97%) rename docs/{developers_server_start.md => developer_server_start.md} (94%) create mode 100644 docs/readme.md create mode 100644 docs/setup.md diff --git a/docs/analysis_start.md b/docs/analysis_start.md index 5405dfe..ed74e78 100644 --- a/docs/analysis_start.md +++ b/docs/analysis_start.md @@ -74,14 +74,18 @@ When the specification changes the version will change according to semantic versioning rules. The OpenAPI definition generated is next used in the -[developer client start](developers_client_start.md) or -[developer server start](developers_server_start.md) flow. +[developer client start](developer_client_start.md) or +[developer server start](developer_server_start.md) flow. The client will need to consume a mock service until the server code is built. # Reading Notes +Further automation can be achieved by GitActions calling +qaskx-cli, such as registering the OpenAPI specification in the +devops file. + The ApiCurio and Github components can be substituted for other software products uch as Swagger Editor and Bitbucket that provide similar capabilities. diff --git a/docs/developers_client_start.md b/docs/developer_client_start.md similarity index 97% rename from docs/developers_client_start.md rename to docs/developer_client_start.md index 1d076af..48a1340 100644 --- a/docs/developers_client_start.md +++ b/docs/developer_client_start.md @@ -60,14 +60,14 @@ sequenceDiagram qaskx ->>+ oas3f: Read dependency oas3f -->>- qaskx: Contents end - Note over cmdb, git: qaskx devops ci cmd + Note over cmdb, git: qaskx-cli rediops ci cmd qaskx ->>+ cmdb: cmdb -->>- qaskx: New CI value qaskx -) devops: Update CI entry qaskx -->>- term: Success term ->>+ qaskx: Generate code - Note over qaskx, cmdb: qaskx gen client cmd + Note over qaskx, cmdb: qaskx-cli gen client cmd qaskx ->>+ devops: Read dependency list devops -->>- qaskx: Contents loop Read called dependencies @@ -83,7 +83,7 @@ sequenceDiagram alt Register using API dependencies if not already done term ->>+ qaskx: Register API dependencies - Note over cmdb, git: qaskx devops register cmd + Note over cmdb, git: qaskx-cli rediops register cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents loop Read called dependencies diff --git a/docs/developers_server_start.md b/docs/developer_server_start.md similarity index 94% rename from docs/developers_server_start.md rename to docs/developer_server_start.md index f7ca3a1..2dbfadc 100644 --- a/docs/developers_server_start.md +++ b/docs/developer_server_start.md @@ -56,6 +56,7 @@ sequenceDiagram alt If no OpenAPI linked qaskx ->>+ git: + Note over oas3f, devops: qaskx-cli rediops scan command Note over oas3f, devops: Scan for OpenAPI file in Git git -->>- qaskx: qaskx -) devops: Update OpenAPI entry @@ -70,12 +71,13 @@ sequenceDiagram qaskx -->>- term: Success term ->>+ qaskx: Generate code - Note over qaskx, cmdb: qaskx gen server cmd + Note over qaskx, cmdb: qaskx-cli gen server cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents alt If no OpenAPI linked qaskx ->>+ git: + Note over oas3f, devops: qaskx-cli rediops scan command Note over oas3f, devops: Scan for OpenAPI file in Git git -->>- qaskx: qaskx -) devops: Update OpenAPI entry @@ -93,7 +95,7 @@ sequenceDiagram alt Register API if not already done term ->>+ qaskx: Register API - Note over cmdb, git: qaskx devops register cmd + Note over cmdb, git: qaskx-cli rediops register cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read @@ -200,6 +202,9 @@ response results. # Reading Notes +For automation, some activities can be performed by GitActions calling +qaskx-cli. + The Visual Studio Code, CMDB and Github components can be substituted for other software products such IntelliJ and Bitbucket. diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..5b01476 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,22 @@ +# Contents + +This is the location for documentation associated with +suggested the **rediops** process. The objective is to increase +the velocity of feature development by using tools to reduce +the repetitious tasks or at least reduce the number of keystrokes. + +The documents should be read in the following sequence: + +* [setup](setup.md) Once of desktop setup +* [project start](project_start.md) Starting a new project or initiative +* [analysis start](analysis_start.md) Focus on technical API analysis +* [developer server_start](developer_server_start.md) Initial server coding +* [developer client_start](developer_client_start.md) Initial client coding +* [developer update](developer_update.md) API updates during the development lifecycle + +The process above is in the context of exposing functionality defined in +API service that can be consumed by clients - commonly a web or app user +interface. + +**All flows are high level process depictions and can +be adjusted to suit your tools** diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..75afb88 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,39 @@ +# Setup desktop (start) + +This is the setup desktop tasks that is performed by +the developers, though others that are updating code +including documentation can also perform the setup. + +This task is expected to be done only once for a desktop +environment, and the environment can be used for +multiple projects and deliveries. + +## Software installation + +Please ensure the following tools or equivalents are +installed or you have access to servers with the +associated capabilities. + +* A Git repository server - Github, Gitea +* Rights to create a Git repo and push content to the remote Git repo +* Integrated development environment (IDE) software - Visual Studio Code, IntelliJ +* Access to an OpenAPI editor - ApiCurio, Swagger UI +* Installed **qaskx-cli** tool +* Access to a Configuration Management Database (CMDB) - ServiceNow, Zenoss +* Access to an API registry portal - Apiman.io, Redocly + + + +# End Status of flow + +At the end of the above setup steps the desktop will have the base tools +that are mentioned in subsequent documents. + +The next step in the process is covered in [project_start](project_start.md) + +# Reading Notes + +The suggested tools are only that, suggestions. You can substitute +your own preferred tools as appropriate. The concept is still valid +and your mileage may vary. + From d1d88707d85fa82892cda49df26ef888de2a29d9 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Tue, 1 Aug 2023 23:50:05 +1000 Subject: [PATCH 06/10] Added Git software for desktop install --- docs/setup.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/setup.md b/docs/setup.md index 75afb88..0bde8d1 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -16,6 +16,7 @@ associated capabilities. * A Git repository server - Github, Gitea * Rights to create a Git repo and push content to the remote Git repo +* Git installed on local desktop * Integrated development environment (IDE) software - Visual Studio Code, IntelliJ * Access to an OpenAPI editor - ApiCurio, Swagger UI * Installed **qaskx-cli** tool From 6d82fc1723ea3291ab808ae0a1f605f107f59b0b Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Wed, 2 Aug 2023 22:55:02 +1000 Subject: [PATCH 07/10] Updated documentation --- docs/analysis_start.md | 4 +- docs/developer_client_start.md | 29 ++++-- docs/developer_server_start.md | 29 ++++-- docs/developer_update.md | 160 ++++++++++++++++++++++++++++++++- docs/project_start.md | 60 +++++++++++++ docs/readme.md | 2 +- docs/setup.md | 10 ++- 7 files changed, 270 insertions(+), 24 deletions(-) diff --git a/docs/analysis_start.md b/docs/analysis_start.md index ed74e78..c19a1e9 100644 --- a/docs/analysis_start.md +++ b/docs/analysis_start.md @@ -25,7 +25,9 @@ size and description. ## Sequence Diagram ```mermaid - +--- +title: Business Analyst task flow +--- sequenceDiagram actor ba as Business Analyst diff --git a/docs/developer_client_start.md b/docs/developer_client_start.md index 48a1340..a185663 100644 --- a/docs/developer_client_start.md +++ b/docs/developer_client_start.md @@ -26,7 +26,9 @@ as follows. The Qaskx command line tool needs to be installed on the developer machine ```mermaid - +--- +title: Client development task flow +--- sequenceDiagram actor dev as Developer @@ -53,17 +55,17 @@ sequenceDiagram end vsc ->>+ term: start - term ->>+ qaskx: New CI + term ->>+ qaskx: New CMDB CI qaskx ->>+ devops: Read devops -->>- qaskx: Contents loop Read called dependencies qaskx ->>+ oas3f: Read dependency oas3f -->>- qaskx: Contents end - Note over cmdb, git: qaskx-cli rediops ci cmd + Note over cmdb, git: qaskx-cli rediops cmdb cmd qaskx ->>+ cmdb: - cmdb -->>- qaskx: New CI value - qaskx -) devops: Update CI entry + cmdb -->>- qaskx: New CMDB CI value + qaskx -) devops: Update CMDB CI entry qaskx -->>- term: Success term ->>+ qaskx: Generate code @@ -99,6 +101,13 @@ sequenceDiagram term -->- vsc: close + rect grey + Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place + vsc -->> vsc: Code update + vsc -->> vsc: Local build + vsc -->> vsc: Local test + end + vsc ->>+ git: Commit git --) git: Trigger GitActions for lint, gateway, features, etc git ->>- vsc: Success @@ -117,7 +126,9 @@ details in various documents The OpenAPI tool needs to be installed on the developer machine. ```mermaid - +--- +title: Client development task flow +--- sequenceDiagram actor dev as Developer @@ -133,9 +144,9 @@ sequenceDiagram participant apip as API portal - Note over cmdb, vsc: Create new CI entry for Client + Note over cmdb, vsc: Create new CMDB CI entry for Client dev ->>+ cmdb: Access UI - cmdb -->> cmdb: Create CI entry + cmdb -->> cmdb: Create CMDB CI entry cmdb -->>- dev: Close, noting CI value Note over git, devops: The devops file is stored in Git @@ -146,7 +157,7 @@ sequenceDiagram vsc ->>+ git : git -->>- vsc : Cloned, project opened - vsc -) devops: Update CI entry + vsc -) devops: Update CMDB CI entry vsc ->>+ term: start Note over git, oas3: Set generation parameters diff --git a/docs/developer_server_start.md b/docs/developer_server_start.md index 2dbfadc..d522453 100644 --- a/docs/developer_server_start.md +++ b/docs/developer_server_start.md @@ -27,7 +27,9 @@ as follows. The Qaskx command line tool needs to be installed on the developer machine ```mermaid - +--- +title: Server development task flow +--- sequenceDiagram actor dev as Developer @@ -50,13 +52,13 @@ sequenceDiagram Note over git, devops: The OpenAPI and devops files are stored in Git vsc ->>+ term: start - term ->>+ qaskx: New CI + term ->>+ qaskx: New CMDB CI qaskx ->>+ devops: Read devops -->>- qaskx: Contents alt If no OpenAPI linked qaskx ->>+ git: - Note over oas3f, devops: qaskx-cli rediops scan command + Note over oas3f, devops: qaskx-cli rediops scan cmd Note over oas3f, devops: Scan for OpenAPI file in Git git -->>- qaskx: qaskx -) devops: Update OpenAPI entry @@ -64,9 +66,9 @@ sequenceDiagram qaskx ->>+ oas3f: Read oas3f -->>- qaskx: Contents - Note over cmdb, git: qaskx devops ci cmd + Note over cmdb, git: qaskx-cli rediops cmdb cmd qaskx ->>+ cmdb: - cmdb -->>- qaskx: New CI value + cmdb -->>- qaskx: New CMDB CI value qaskx -) devops: Update CI entry qaskx -->>- term: Success @@ -77,7 +79,7 @@ sequenceDiagram alt If no OpenAPI linked qaskx ->>+ git: - Note over oas3f, devops: qaskx-cli rediops scan command + Note over oas3f, devops: qaskx-cli rediops scan cmd Note over oas3f, devops: Scan for OpenAPI file in Git git -->>- qaskx: qaskx -) devops: Update OpenAPI entry @@ -92,6 +94,13 @@ sequenceDiagram qaskx -) devops: Auto update entries, including build, test qaskx -->>- term: Success + rect grey + Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place + vsc -->> vsc: Code update + vsc -->> vsc: Local build + vsc -->> vsc: Local test + end + alt Register API if not already done term ->>+ qaskx: Register API @@ -127,7 +136,9 @@ details in various documents The OpenAPI tool needs to be installed on the developer machine. ```mermaid - +--- +title: Server development task flow +--- sequenceDiagram actor dev as Developer @@ -143,7 +154,7 @@ sequenceDiagram participant apip as API portal - Note over cmdb, vsc: Create new CI entry for API + Note over cmdb, vsc: Create new CMDB CI entry for API dev ->>+ cmdb: Access UI cmdb -->> cmdb: Create CI entry cmdb -->>- dev: Close, noting CI value @@ -156,7 +167,7 @@ sequenceDiagram vsc ->>+ git : git -->>- vsc : Cloned, project opened - vsc -) devops: Update CI entry + vsc -) devops: Update CMDB CI entry alt If no OpenAPI linked vsc -) devops: Update OpenAPI entry diff --git a/docs/developer_update.md b/docs/developer_update.md index 7d3b69a..4eee25c 100644 --- a/docs/developer_update.md +++ b/docs/developer_update.md @@ -3,8 +3,166 @@ _This document is intended to cover the scenario where the **devops** file contents change including references to OpenAPI specifications._ -_This document under construction._ +## Update the OpenAPI specification +The OpenAPI specification as linked to the publishing server +is updated first. + +```mermaid +--- +title: Business Analyst update task flow +--- +sequenceDiagram + + actor ba as Business Analyst + participant ide as ApiCurio + participant git as Github + participant oas3f as OpenAPI file + + Note over git, oas3f: The OpenAPI file is stored in Git + + ba ->>+ ide: start IDE + + ide ->> ide: Update API specification + ide ->> ide: Create / alter data structures + Note over ba, oas3f: Data structures include requests and responses + ide ->> ide: Create / alter new paths and methods + Note over ba, oas3f: Includes non 200 response handling, headers and security + ide ->> ide: Update the specification version + + ide ->>+ git: Commit to git + git ->>+ oas3f: OpenAPI file under Git + oas3f -->>- git: Saved + git --) git: Trigger GitActions for lint + git -->>- ide: + + ide -->>- ba: close + +``` + +## Server update + +Once the OpenAPI definition has been updated the server code needs to be +re-generated as the publisher of the API. + +```mermaid +--- +title: Server development update task flow +--- +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant term as Terminal + participant qaskx as qaskx-cli + participant git as Github + link git: GitHub @ https://github.com/meerkat-manor/devops + participant oas3f as OpenAPI file + participant devops as devops file + participant apip as API portal + + dev ->>+ vsc: start IDE + + Note over vsc, term: Clone existing git for project + vsc ->>+ git : + git -->>- vsc : Cloned, project opened + + Note over git, devops: The OpenAPI and devops files are stored in Git + + vsc ->>+ term: start + + term ->>+ qaskx: Generate code + Note over qaskx, cmdb: qaskx-cli gen server cmd + qaskx ->>+ devops: Read + devops -->>- qaskx: Contents + + qaskx ->>+ oas3f: Read + oas3f -->>- qaskx: Contents + qaskx -) qaskx: Auto generate server code + opt + qaskx -) qaskx: Auto generate sequence diagram + end + qaskx -->>- term: Success + + term -->- vsc: close + + rect grey + Note over vsc, qaskx: Code updates to use the updated OpenAPI definition + vsc -->> vsc: Code update + vsc -->> vsc: Local build + vsc -->> vsc: Local test + end + + vsc ->>+ git: Commit + git --) git: Trigger GitActions for lint, gateway, features, etc + git ->>- vsc: Success + + vsc -->>- dev: close + +``` + + +## Client update + +Once the OpenAPI definition has been updated the client code needs to be +re-generated as the consumer of the API. + + +```mermaid +--- +title: Client development update task flow +--- +sequenceDiagram + + actor dev as Developer + participant vsc as Visual Studio Code + participant term as Terminal + participant qaskx as qaskx-cli + participant git as Github + link git: GitHub @ https://github.com/meerkat-manor/devops + participant oas3f as OpenAPI file + participant devops as devops file + + dev ->>+ vsc: start IDE + + Note over vsc, term: Clone existing git for project + vsc ->>+ git : + git -->>- vsc : Cloned, project opened + + vsc ->>+ term: start + + term ->>+ qaskx: Generate code + Note over qaskx, cmdb: qaskx-cli gen client cmd + qaskx ->>+ devops: Read dependency list + devops -->>- qaskx: Contents + loop Read called dependencies + qaskx ->>+ oas3f: Read dependency + oas3f -->>- qaskx: Contents + qaskx -) qaskx: Auto generate client code + end + opt + qaskx -) qaskx: Auto generate sequence diagram + end + qaskx -->>- term: Success + + term -->- vsc: close + + rect grey + Note over vsc, qaskx: Code updates to use the updated OpenAPI definition + vsc -->> vsc: Code update + vsc -->> vsc: Local build + vsc -->> vsc: Local test + end + + vsc ->>+ git: Commit + git --) git: Trigger GitActions for lint, gateway, features, etc + git ->>- vsc: Success + + vsc -->>- dev: close + +``` + +The code is now updated with the latest OpenAPI definition # End Status of flow diff --git a/docs/project_start.md b/docs/project_start.md index f332f3f..c617f09 100644 --- a/docs/project_start.md +++ b/docs/project_start.md @@ -3,6 +3,66 @@ _This document under construction._ +## Sequence diagram + +```mermaid + +sequenceDiagram + + + actor person as Team Member + participant term as Terminal + participant qaskx as qaskx-cli + participant git as Github + + person ->>+ term: start + + Note over term, git: Allocate repo name for server + + term ->>+ qaskx: + Note over git: qaskx-cli rediops git (*) cmd + qaskx ->>+ git: + git -->>- qaskx: New git created + qaskx -->>- term: Success + + term ->>+ git: git clone + git -->>- term: + + term ->>+ qaskx: qaskx-cli rediops configure cmd + qaskx -->>- term: + + term ->>+ git: git commit & push + git -->>- term: + + opt Only applicable for new clients (web, mobile) + Note over term, git: Allocate repo name for client + + term ->>+ qaskx: + Note over git: qaskx-cli rediops git (*) cmd + qaskx ->>+ git: + git -->>- qaskx: New git created + qaskx -->>- term: Success + + term ->>+ git: git clone + git -->>- term: + + term ->>+ qaskx: qaskx-cli rediops configure cmd + qaskx -->>- term: + + term ->>+ git: git commit & push + git -->>- term: + end + + term -->>- person: + +``` + +The git repositories are now primed and ready for API specification. + +The tasks in the sequence diagram is provisioning the required repositories. +The client repo may already exist for other functionality in which cas it is not +created, but will be used in the [developer client start](developer_client_start.md) + # End Status of flow At the end of this flow the scope of the API delivery and the service domain diff --git a/docs/readme.md b/docs/readme.md index 5b01476..082f64f 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -7,7 +7,7 @@ the repetitious tasks or at least reduce the number of keystrokes. The documents should be read in the following sequence: -* [setup](setup.md) Once of desktop setup +* [setup](setup.md) Once off desktop setup * [project start](project_start.md) Starting a new project or initiative * [analysis start](analysis_start.md) Focus on technical API analysis * [developer server_start](developer_server_start.md) Initial server coding diff --git a/docs/setup.md b/docs/setup.md index 0bde8d1..6a3a24a 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -17,18 +17,22 @@ associated capabilities. * A Git repository server - Github, Gitea * Rights to create a Git repo and push content to the remote Git repo * Git installed on local desktop -* Integrated development environment (IDE) software - Visual Studio Code, IntelliJ +* Integrated development environment (IDE) software on local desktop - Visual Studio Code, IntelliJ * Access to an OpenAPI editor - ApiCurio, Swagger UI -* Installed **qaskx-cli** tool +* Installed **qaskx-cli** tool on local desktop - download from *TBA* * Access to a Configuration Management Database (CMDB) - ServiceNow, Zenoss * Access to an API registry portal - Apiman.io, Redocly +The server based software above could be executed as docker images +on your local desktop, but this would be only for +demonstration purposes. # End Status of flow At the end of the above setup steps the desktop will have the base tools -that are mentioned in subsequent documents. +that are mentioned in subsequent documents, and you will have +access to the server features. The next step in the process is covered in [project_start](project_start.md) From 417ed7f7e4d24ea640d5d5441e193e8c7c3a9476 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Wed, 2 Aug 2023 23:07:38 +1000 Subject: [PATCH 08/10] Recognise server can be client --- docs/developer_client_start.md | 4 ++-- docs/developer_server_start.md | 22 ++++++++++++++++++++-- docs/developer_update.md | 24 +++++++++++++++++++++--- 3 files changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/developer_client_start.md b/docs/developer_client_start.md index a185663..b101c71 100644 --- a/docs/developer_client_start.md +++ b/docs/developer_client_start.md @@ -101,13 +101,13 @@ sequenceDiagram term -->- vsc: close - rect grey + rect lightgrey Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place vsc -->> vsc: Code update vsc -->> vsc: Local build vsc -->> vsc: Local test end - + vsc ->>+ git: Commit git --) git: Trigger GitActions for lint, gateway, features, etc git ->>- vsc: Success diff --git a/docs/developer_server_start.md b/docs/developer_server_start.md index d522453..28e884b 100644 --- a/docs/developer_server_start.md +++ b/docs/developer_server_start.md @@ -24,6 +24,9 @@ The assumptions for this documents are: The sequence of automation activity using **devops** file and **qaskx-cli** is as follows. +**A server can also be a consumer of other APIs in which case it needs to generate +when downstream API specifications client code.** + The Qaskx command line tool needs to be installed on the developer machine ```mermaid @@ -94,13 +97,28 @@ sequenceDiagram qaskx -) devops: Auto update entries, including build, test qaskx -->>- term: Success - rect grey + opt + + term ->>+ qaskx: Generate code + Note over qaskx, cmdb: qaskx-cli gen client cmd + qaskx ->>+ devops: Read dependency list + devops -->>- qaskx: Contents + loop Read called dependencies + qaskx ->>+ oas3f: Read dependency + oas3f -->>- qaskx: Contents + qaskx -) qaskx: Auto generate client code + end + qaskx -->>- term: Success + + end + + rect lightgrey Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place vsc -->> vsc: Code update vsc -->> vsc: Local build vsc -->> vsc: Local test end - + alt Register API if not already done term ->>+ qaskx: Register API diff --git a/docs/developer_update.md b/docs/developer_update.md index 4eee25c..8fea050 100644 --- a/docs/developer_update.md +++ b/docs/developer_update.md @@ -45,6 +45,9 @@ sequenceDiagram Once the OpenAPI definition has been updated the server code needs to be re-generated as the publisher of the API. +**A server can also be a consumer of other APIs in which case it needs updating +when downstream API specifications change.** + ```mermaid --- title: Server development update task flow @@ -84,15 +87,30 @@ sequenceDiagram end qaskx -->>- term: Success + opt + + term ->>+ qaskx: Generate code + Note over qaskx, cmdb: qaskx-cli gen client cmd + qaskx ->>+ devops: Read dependency list + devops -->>- qaskx: Contents + loop Read called dependencies + qaskx ->>+ oas3f: Read dependency + oas3f -->>- qaskx: Contents + qaskx -) qaskx: Auto generate client code + end + qaskx -->>- term: Success + + end + term -->- vsc: close - rect grey + rect lightgrey Note over vsc, qaskx: Code updates to use the updated OpenAPI definition vsc -->> vsc: Code update vsc -->> vsc: Local build vsc -->> vsc: Local test end - + vsc ->>+ git: Commit git --) git: Trigger GitActions for lint, gateway, features, etc git ->>- vsc: Success @@ -147,7 +165,7 @@ sequenceDiagram term -->- vsc: close - rect grey + rect lightgrey Note over vsc, qaskx: Code updates to use the updated OpenAPI definition vsc -->> vsc: Code update vsc -->> vsc: Local build From 248ad6fcdb7dc26b138b6c3b606f43f0f2d3f0c0 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Thu, 3 Aug 2023 21:42:42 +1000 Subject: [PATCH 09/10] Expanded install and project --- docs/config/dot_qaskx.md | 29 +++++++++++++++++++++++ docs/project_start.md | 16 +++++++++++-- docs/setup.md | 50 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 93 insertions(+), 2 deletions(-) create mode 100644 docs/config/dot_qaskx.md diff --git a/docs/config/dot_qaskx.md b/docs/config/dot_qaskx.md new file mode 100644 index 0000000..4d64b00 --- /dev/null +++ b/docs/config/dot_qaskx.md @@ -0,0 +1,29 @@ +# .qaskx file + +The .qaskx (dotqaskx) file is normally located in +your home directory. The file is a basic, short +configuration file for items that are shared +across projects, such as your Git details. + +A sample file is: + +```json +{ + "GitProvider": "git", + "GitHost": "https://tea.example.com", + "GitApi": "https://tea.example.com/api/v1", + "GitOrg": "Wardrobe", + "GitRepoUser": "meerkat", + "GitBranch": "main", + "GitUserEmail": "meerkat@example.com", + "Organisation": "Witch & Wardrobe", + "TemplateHost": "", + "TemplateFolder": "Xtreme/Folder/Template", + "Name": "Sir Meerkat", + "ServiceOwner": "Meerkat team, Sydney", + "ServiceOwnerEmail": "Meerkat.Team@example.com", + "PrimaryProgramLanguage": "go", + "LintApiLevel": "" +} +``` + diff --git a/docs/project_start.md b/docs/project_start.md index c617f09..b640a34 100644 --- a/docs/project_start.md +++ b/docs/project_start.md @@ -1,7 +1,19 @@ -# Project flow +# Project flow (start) -_This document under construction._ +The project inception is when the scope of the project is +defined, but design and coding does not start immediately. +**Pause and reflect before starting to design and pause again +to reflect on the design before starting to code.** + +With experience you will find that many times your initial gut instinct +on design is correct, but **many is not the same as always**. With the right +tools, refactoring does allow you to change designs/code quickly - but a +pause over lunch or a night's sleep costs little and can help +you organise your approach. + +The sequence diagram below starts when you have an idea that you need +new code and existing code cannot be modified to suit your needs. ## Sequence diagram diff --git a/docs/setup.md b/docs/setup.md index 6a3a24a..1c0804d 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -27,6 +27,56 @@ The server based software above could be executed as docker images on your local desktop, but this would be only for demonstration purposes. +Configuring and initialising the software above is left for you to follow +any existing standards you may have. The qaskc-cli setup is below. + +## Sequence diagram + +The qaskx-cli has a setup command that creates the basic configuration +files that it uses. If or when you need to change the defaults, you will +commonly make the changes permanent by changing the configuration files. + +This includes items such as: + +* Your details and your organisation +* Your git details +* Preferred programming language +* Template (remote) locations + +You can read further information on each file in documents: + +* [.qaskx](config/dotaskx.md) + +Now have a look at the steps below to setup the files. + +```mermaid + +sequenceDiagram + + + actor person as Team Member + participant term as Terminal + participant qaskx as qaskx-cli + participant home as home dir + participant prj as projects dir + + person ->>+ term: start + + Note over term, qaskx: Setup qaskx-cli tool + + term ->>+ qaskx: + Note over qaskx, home: qaskx-cli setup configure cmd + qaskx ->>+ home: + home -->>- qaskx: New .qaskx file created + qaskx ->>+ prj: + prj -->>- qaskx: New config file created + qaskx -->>- term: Success + + Note over term, home: You can rerun the configure or modify config file + + term -->>- person: + +``` # End Status of flow From d52bdaeb61d1bb4ebc5d59255f96255c2eb3ba32 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Thu, 3 Aug 2023 21:59:44 +1000 Subject: [PATCH 10/10] Added template files --- templates/default/.qaskx | 17 +++++ templates/default/devops.json | 134 ++++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 templates/default/.qaskx create mode 100644 templates/default/devops.json diff --git a/templates/default/.qaskx b/templates/default/.qaskx new file mode 100644 index 0000000..663603b --- /dev/null +++ b/templates/default/.qaskx @@ -0,0 +1,17 @@ +{ + "GitProvider": "git", + "GitHost": "https://tea.example.com", + "GitApi": "https://tea.merebox.com/api/v1", + "GitOrg": "Wardrobe", + "GitRepoUser": "meerkat", + "GitBranch": "main", + "GitUserEmail": "meerkat@example.com", + "Organisation": "Witch & Wardrobe", + "TemplateHost": "", + "TemplateFolder": "Xtreme/Folder/Template", + "Name": "Sir Meerkat", + "ServiceOwner": "Meerkat team, Sydney", + "ServiceOwnerEmail": "Meerkat.Team@example.com", + "PrimaryProgramLanguage": "go", + "LintApiLevel": "" +} \ No newline at end of file diff --git a/templates/default/devops.json b/templates/default/devops.json new file mode 100644 index 0000000..9f9411d --- /dev/null +++ b/templates/default/devops.json @@ -0,0 +1,134 @@ +{ + "apis": [ + { + "api": { + "category": "API", + "name": "", + "url": "" + }, + "format": "OpenAPI", + "guide": "", + "release_id": "", + "service_id": "", + "name": "AService", + "url": "" + }, + { + "api": { + "category": "API", + "name": "", + "url": "" + }, + "format": "AsyncAPI", + "guide": "", + "release_id": "", + "service_id": "", + "name": "BService", + "url": "" + } + ], + "asset": { + "id": "b6775b43-659d-4426-b012-3226a7cfdd56", + "name": "", + "url": "" + }, + "build": [ + { + "activity": { + "category": "BUILD", + "name": "Lint", + "url": "" + }, + "config": "", + "guide": "" + }, + { + "activity": { + "category": "BUILD", + "name": "Compile", + "url": "" + }, + "config": "", + "guide": "" + } + ], + "created_on": "2023-07-09T07:05:38.8634596+10:00", + "dependency": { + "apis": [ + { + "api": { + "category": "API", + "name": "", + "url": "" + }, + "format": "OpenAPI", + "guide": "", + "release_id": "v1", + "service_id": "Customer.Details.CI00001", + "url": "" + } + ], + "guide": "", + "tools": [ + { + "commands": null, + "guide": "", + "playbook": "", + "tool": { + "category": "CUSTOM", + "name": "", + "url": "" + } + } + ] + }, + "devops_version": "0.0.1", + "guide": "", + "install": { + "commands": { + "script": "" + }, + "deploy": { + "category": "DEPLOY", + "name": "rpm", + "url": "" + }, + "guide": "", + "playbook": "" + }, + "name": "Wardrobe", + "organisation": "Witch & Wardrobe", + "owner": { + "email": "", + "matrix": "", + "name": "", + "slack": "", + "twitter": "", + "web": "" + }, + "tags": [ + "" + ], + "test": [ + { + "activity": { + "category": "TEST", + "name": "", + "url": "" + }, + "config": "", + "guide": "" + }, + { + "activity": { + "category": "TEST", + "name": "LoadRunner", + "url": "" + }, + "config": "", + "guide": "" + } + ], + "unique_id": "48913292-dc8a-4fb6-99cd-c22ab445e0ee", + "updated_on": "2023-07-09T07:05:38.8634596+10:00" +} \ No newline at end of file