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)