181 lines
4.6 KiB
Markdown
181 lines
4.6 KiB
Markdown
# Developer update flow
|
|
|
|
_This document is intended to cover the scenario where the **devops**
|
|
file contents change including references to OpenAPI specifications._
|
|
|
|
## 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
|
|
|
|
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.
|