rediOps

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.

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

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

Client update

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

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.