This document is intended to cover the scenario where the devops file contents change including references to OpenAPI specifications.
The OpenAPI specification as linked to the publishing server is updated first.
---
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
Once the OpenAPI definition has been updated the server code needs to be re-generated as the publisher of the API.
A server can also be a consumer of other APIs in which case it needs updating when downstream API specifications change.
---
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
opt
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
qaskx -->>- term: Success
end
term -->- vsc: close
rect lightgrey
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
Once the OpenAPI definition has been updated the client code needs to be re-generated as the consumer of the API.
---
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 lightgrey
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
At the end of this flow the code has been updated with latest definitions.
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.