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