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.