Wardrobe
/
rediOps
mirror of https://github.com/meerkat-manor/rediOps.git
5
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated documentation

documentation
meerkat-manor 2023-08-02 22:55:02 +10:00
parent d1d88707d8
commit 6d82fc1723
7 changed files with 270 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/analysis_start.md
View File

@ -25,7 +25,9 @@ size and description.
## Sequence Diagram
```mermaid
---
title: Business Analyst task flow
---
sequenceDiagram
actor ba as Business Analyst

29
docs/developer_client_start.md
View File

@ -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

29
docs/developer_server_start.md
View File

@ -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

160
docs/developer_update.md
View File

@ -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

60
docs/project_start.md
View File

@ -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

2
docs/readme.md
View File

@ -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

10
docs/setup.md
View File

@ -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)