From 19f52c2d3d836a66da15350198e97eee136812d9 Mon Sep 17 00:00:00 2001 From: meerkat-manor Date: Tue, 1 Aug 2023 23:46:54 +1000 Subject: [PATCH] Adding documentation --- docs/analysis_start.md | 8 +++- ...ent_start.md => developer_client_start.md} | 6 +-- ...ver_start.md => developer_server_start.md} | 9 ++++- docs/readme.md | 22 +++++++++++ docs/setup.md | 39 +++++++++++++++++++ 5 files changed, 77 insertions(+), 7 deletions(-) rename docs/{developers_client_start.md => developer_client_start.md} (97%) rename docs/{developers_server_start.md => developer_server_start.md} (94%) create mode 100644 docs/readme.md create mode 100644 docs/setup.md diff --git a/docs/analysis_start.md b/docs/analysis_start.md index 5405dfe..ed74e78 100644 --- a/docs/analysis_start.md +++ b/docs/analysis_start.md @@ -74,14 +74,18 @@ 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. +[developer client start](developer_client_start.md) or +[developer server start](developer_server_start.md) flow. The client will need to consume a mock service until the server code is built. # Reading Notes +Further automation can be achieved by GitActions calling +qaskx-cli, such as registering the OpenAPI specification in the +devops file. + The ApiCurio and Github components can be substituted for other software products uch as Swagger Editor and Bitbucket that provide similar capabilities. diff --git a/docs/developers_client_start.md b/docs/developer_client_start.md similarity index 97% rename from docs/developers_client_start.md rename to docs/developer_client_start.md index 1d076af..48a1340 100644 --- a/docs/developers_client_start.md +++ b/docs/developer_client_start.md @@ -60,14 +60,14 @@ sequenceDiagram qaskx ->>+ oas3f: Read dependency oas3f -->>- qaskx: Contents end - Note over cmdb, git: qaskx devops ci cmd + Note over cmdb, git: qaskx-cli rediops ci cmd qaskx ->>+ cmdb: cmdb -->>- qaskx: New CI value qaskx -) devops: Update CI entry qaskx -->>- term: Success term ->>+ qaskx: Generate code - Note over qaskx, cmdb: qaskx gen client cmd + Note over qaskx, cmdb: qaskx-cli gen client cmd qaskx ->>+ devops: Read dependency list devops -->>- qaskx: Contents loop Read called dependencies @@ -83,7 +83,7 @@ sequenceDiagram alt Register using API dependencies if not already done term ->>+ qaskx: Register API dependencies - Note over cmdb, git: qaskx devops register cmd + Note over cmdb, git: qaskx-cli rediops register cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents loop Read called dependencies diff --git a/docs/developers_server_start.md b/docs/developer_server_start.md similarity index 94% rename from docs/developers_server_start.md rename to docs/developer_server_start.md index f7ca3a1..2dbfadc 100644 --- a/docs/developers_server_start.md +++ b/docs/developer_server_start.md @@ -56,6 +56,7 @@ sequenceDiagram alt If no OpenAPI linked qaskx ->>+ git: + Note over oas3f, devops: qaskx-cli rediops scan command Note over oas3f, devops: Scan for OpenAPI file in Git git -->>- qaskx: qaskx -) devops: Update OpenAPI entry @@ -70,12 +71,13 @@ sequenceDiagram qaskx -->>- term: Success term ->>+ qaskx: Generate code - Note over qaskx, cmdb: qaskx gen server cmd + Note over qaskx, cmdb: qaskx-cli gen server cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents alt If no OpenAPI linked qaskx ->>+ git: + Note over oas3f, devops: qaskx-cli rediops scan command Note over oas3f, devops: Scan for OpenAPI file in Git git -->>- qaskx: qaskx -) devops: Update OpenAPI entry @@ -93,7 +95,7 @@ sequenceDiagram alt Register API if not already done term ->>+ qaskx: Register API - Note over cmdb, git: qaskx devops register cmd + Note over cmdb, git: qaskx-cli rediops register cmd qaskx ->>+ devops: Read devops -->>- qaskx: Contents qaskx ->>+ oas3f: Read @@ -200,6 +202,9 @@ response results. # Reading Notes +For automation, some activities can be performed by GitActions calling +qaskx-cli. + The Visual Studio Code, CMDB and Github components can be substituted for other software products such IntelliJ and Bitbucket. diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..5b01476 --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,22 @@ +# Contents + +This is the location for documentation associated with +suggested the **rediops** process. The objective is to increase +the velocity of feature development by using tools to reduce +the repetitious tasks or at least reduce the number of keystrokes. + +The documents should be read in the following sequence: + +* [setup](setup.md) Once of desktop setup +* [project start](project_start.md) Starting a new project or initiative +* [analysis start](analysis_start.md) Focus on technical API analysis +* [developer server_start](developer_server_start.md) Initial server coding +* [developer client_start](developer_client_start.md) Initial client coding +* [developer update](developer_update.md) API updates during the development lifecycle + +The process above is in the context of exposing functionality defined in +API service that can be consumed by clients - commonly a web or app user +interface. + +**All flows are high level process depictions and can +be adjusted to suit your tools** diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..75afb88 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,39 @@ +# Setup desktop (start) + +This is the setup desktop tasks that is performed by +the developers, though others that are updating code +including documentation can also perform the setup. + +This task is expected to be done only once for a desktop +environment, and the environment can be used for +multiple projects and deliveries. + +## Software installation + +Please ensure the following tools or equivalents are +installed or you have access to servers with the +associated capabilities. + +* A Git repository server - Github, Gitea +* Rights to create a Git repo and push content to the remote Git repo +* Integrated development environment (IDE) software - Visual Studio Code, IntelliJ +* Access to an OpenAPI editor - ApiCurio, Swagger UI +* Installed **qaskx-cli** tool +* Access to a Configuration Management Database (CMDB) - ServiceNow, Zenoss +* Access to an API registry portal - Apiman.io, Redocly + + + +# End Status of flow + +At the end of the above setup steps the desktop will have the base tools +that are mentioned in subsequent documents. + +The next step in the process is covered in [project_start](project_start.md) + +# Reading Notes + +The suggested tools are only that, suggestions. You can substitute +your own preferred tools as appropriate. The concept is still valid +and your mileage may vary. +