Created various flow documents
parent
940bc1931d
commit
80e8fdc9ab
|
|
@ -1,9 +1,4 @@
|
||||||
|
# Background
|
||||||
|
|
||||||
|
_This document is under construction_
|
||||||
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
|
|
||||||
mindmaps
|
|
||||||
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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
|
|
||||||
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
@ -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.
|
||||||
|
|
||||||
|
|
@ -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.
|
||||||
|
|
||||||
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue