feat(LH-89186): Write maintainable CLI tool for API doc and SDK gener…

…ation (#62)

.github/CODEOWNERS

@@ -0,0 +1 @@
+*                           @cisco-lockhart/cdo-platform-team  @cisco-lockhart/public-api-approvers

.github/workflows/golang.yml

@@ -0,0 +1,87 @@
+name: build OpenAPI docs generation tool
+on:
+  push:
+    branches: [ master, main ]
+    paths:
+      - scripts/golang/**
+  pull_request:
+    branches: [ master, main ]
+    paths:
+      - scripts/golang/**
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Install dependencies
+        working-directory: scripts/golang
+        run: |
+          go mod tidy
+          go install github.com/onsi/ginkgo/v2/ginkgo@latest
+
+      - name: Run tests
+        working-directory: scripts/golang
+        run: |
+          ginkgo -r -v
+
+      - name: Build Snapshots using Goreleaser
+        if: github.ref != 'refs/heads/main'
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          args: release --snapshot
+          workdir: 'scripts/golang'
+
+      - name: Archive Snapshots
+        if: github.ref != 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-snapshots
+          path: scripts/golang/dist/*.tar.gz
+
+      # when branch is main, release a new version
+      - name: Bump version and push tag
+        id: tag_version
+        if: github.ref == 'refs/heads/main'
+        uses: mathieudutour/github-tag-action@v6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+  release:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Build using Goreleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          args: release
+          workdir: 'scripts/golang'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: jfrog/setup-jfrog-cli@v4
+        env:
+          JF_URL: ${{ vars.ARTIFACTORY_URL }}
+          JF_ACCESS_TOKEN: ${{ secrets.ARTIFACTORY_ACCESS_TOKEN }}

.gitignore

@@ -1 +1,7 @@
 node_modules/
+.DS_Store
+**/.idea
+**/.DS_Store
+scripts/golang/sdks/
+scripts/golang/openapitools.json
+**/cloud-fw-mgr-api-docs

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# How to Contribute
+
+Thank you for your interest in contributing to this repository. If you are not a Cisco employee, we 
+unfortunately cannot accept pull request submissions from you. However, we welcome you to open issues.
+
+If you are a Cisco employee who is working on a microservice that will become part of this repository, read on.
+
+# Adding a new microservice
+
+- Edit `cloud-fw-mgr-api-docs.config.yaml` in the root of this repo, and add the new microservice to
+  the `services` section. For example:
+
+```yaml
+  - name: "my-new-service"
+    url: "https://staging.manage.security.cisco.com/api/platform/my-new-service/v3/api-docs.yaml"
+```
+- Edit `api-changelog.md` to add a short description of what APIs your new microservice provides.
+- Submit a PR (please see commit message guidelines).
+- You will need approval from the CODEOWNERS. See `.github/CODEOWNERS` to see who to request
+  approval from.
+- Once your PR is approved, you will be (Cisco network only) be able to view the changes at
+  [https://devnetapps.cisco.com/docs/cisco-security-cloud-control/](https://devnetapps.cisco.com/docs/cisco-security-cloud-control/).
+- To get it published to [https://developer.cisco.com/docs/cisco-security-cloud-control](https://developer.cisco.com/docs/cisco-security-cloud-control),
+  please work with the Cisco Devnet team or [Siddhu Warrier](mailto:siwarrie@cisco.com), as this is a manual process that will involve reviewing the APIs you have added to ensure
+  that they meet Cisco style guidelines.
+
+# Making API changes to an existing microservice
+
+## My change is backwards-incompatible
+
+To adhere to Cisco's policy around backwards compatibility, you **cannot** make backwards-incompatible changes to an existing microservice.
+If you need to make a backwards-incompatible change, please work with [Jeremy Street](mailto:jerestre@cisco.com) and [Siddhu Warrier](mailto:siwarrie@cisco.com).
+
+## My change is backwards-compatible
+
+This can involve adding new APIs, or changing existing in APIs in a backwards-compatible manner.
+
+- Edit `api-changelog.md` to add a short description of what APIs your new microservice provides.
+- Submit a PR (please see commit message guidelines).
+- You will need approval from the CODEOWNERS. See `.github/CODEOWNERS` to see who to request
+  approval from.
+- Once your PR is approved, you will be (Cisco network only) be able to view the changes at
+  [https://devnetapps.cisco.com/docs/cisco-security-cloud-control/](https://devnetapps.cisco.com/docs/cisco-security-cloud-control/).
+- To get it published to [https://developer.cisco.com/docs/cisco-security-cloud-control](https://developer.cisco.com/docs/cisco-security-cloud-control),
+  please work with the Cisco Devnet team or [Siddhu Warrier](mailto:siwarrie@cisco.com), as this is a manual process that will involve reviewing the APIs you have added to ensure
+  that they meet Cisco style guidelines.

README.md

@@ -1,8 +1,93 @@
 # Welcome to the Cisco Security Cloud Control Public API Documentation
 
-These docs are published to DevNet using PubHub. 
+These docs are published to DevNet using PubHub.
 
 See [https://pubhub.cisco.com/detail/5082] or contact siwarrie@cisco.com for details
 
 ## View your changes
+
 Go to [https://devnetapps.cisco.com/docs/cisco-defense-orchestrator/].
+
+# Contributions
+
+- PRs with changes to this file will only accepted from contributors who work for Cisco, who use
+  a Github account associated with their Cisco email address to create the PR.
+
+## Adding a new microservice
+
+- Edit `cloud-fw-mgr-api-docs.config.yaml` in the root of this repo, and add the new microservice to
+  the `services` section. For example:
+
+```yaml
+  - name: "my-new-service"
+    url: "https://staging.manage.security.cisco.com/api/platform/my-new-service/v3/api-docs.yaml"
+```
+- Edit `api-changelog.md` to add a short description of what APIs your new microservice provides.
+- Submit a PR (please see commit message guidelines).
+- You will need approval from the CODEOWNERS. See `.github/CODEOWNERS` to see who to request
+  approval from.
+- Once your PR is approved, you will be (Cisco network only) be able to view the changes at
+  [https://devnetapps.cisco.com/docs/cisco-security-cloud-control/](https://devnetapps.cisco.com/docs/cisco-security-cloud-control/).
+- To get it published to [https://developer.cisco.com/docs/cisco-security-cloud-control](https://developer.cisco.com/docs/cisco-security-cloud-control),
+  please work with the Cisco Devnet team or [Siddhu Warrier](mailto:siwarrie@cisco.com), as this is a manual process that will involve reviewing the APIs you have added to ensure
+  that they meet Cisco style guidelines.
+
+## Making API changes to an existing microservice
+
+### My change is backwards-incompatible
+
+To adhere to Cisco's policy around backwards compatibility, you **cannot** make backwards-incompatible changes to an existing microservice.
+If you need to make a backwards-incompatible change, please work with [Jeremy Street](mailto:jerestre@cisco.com) and [Siddhu Warrier](mailto:siwarrie@cisco.com).
+
+### My change is backwards-compatible
+
+This can involve adding new APIs, or changing existing in APIs in a backwards-compatible manner.
+
+- Edit `api-changelog.md` to add a short description of what APIs your new microservice provides.
+- Submit a PR (please see commit message guidelines).
+- You will need approval from the CODEOWNERS. See `.github/CODEOWNERS` to see who to request
+  approval from.
+- Once your PR is approved, you will be (Cisco network only) be able to view the changes at
+  [https://devnetapps.cisco.com/docs/cisco-security-cloud-control/](https://devnetapps.cisco.com/docs/cisco-security-cloud-control/).
+- To get it published to [https://developer.cisco.com/docs/cisco-security-cloud-control](https://developer.cisco.com/docs/cisco-security-cloud-control),
+  please work with the Cisco Devnet team or [Siddhu Warrier](mailto:siwarrie@cisco.com), as this is a manual process that will involve reviewing the APIs you have added to ensure
+  that they meet Cisco style guidelines.
+
+## PR guidelines
+
+All PR commits should follow
+the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format.
+This will help us automate the release process, and we will set the version of the CLI on the basis
+of the commit made.
+
+# The Golang CLI for API documentation generation
+
+## Pre-requisites
+
+- Install Golang: https://golang.org/doc/install
+- Install cobra-cli: `go install github.com/spf13/cobra-cli@latest`
+- Install pre-requisites:
+
+```shell
+go run main.go install-pre-reqs
+```
+
+## Development
+
+### Add a new command
+
+```shell
+cobra-cli add <command-name>
+```
+
+### Testing
+
+All tests are written using [Ginkgo](https://github.com/onsi/ginkgo)
+and [Gomega](https://github.com/onsi/gomega).
+
+To run your tests, use the following command:
+
+```shell
+cd /path/to/scripts/golang
+ginkgo -r
+```

cloud-fw-mgr-api-docs.config.yaml

@@ -0,0 +1,40 @@
+services:
+  - name: "api-facade"
+    url: "https://staging.manage.security.cisco.com/api/platform/public-api/v3/api-docs.yaml"
+  - name: "msp-api"
+    url: "https://staging.manage.security.cisco.com/api/platform/msp-api/v3/api-docs.yaml"
+  - name: "device-upgrade"
+    url: "https://staging.manage.security.cisco.com/api/platform/device-upgrade/v3/api-docs.yaml"
+  - name: "object-service"
+    url: "https://staging.manage.security.cisco.com/api/platform/object-service/v3/api-docs.yaml"
+  - name: "transaction-service"
+    url: "https://staging.manage.security.cisco.com/api/platform/transaction-service/v3/api-docs.yaml"
+info:
+  title: "Cisco Security Cloud Control API"
+  version: "1.5.0"
+  description: "Use the documentation to explore the endpoints Security Cloud Control has to offer"
+  contact:
+    name: "Cisco Security Cloud Control TAC"
+    email: "cdo.tac@cisco.com"
+servers:
+ - url: https://edge.us.cdo.cisco.com/api/rest
+   description: US
+ - url: https://edge.eu.cdo.cisco.com/api/rest
+   description: EU
+ - url: https://edge.apj.cdo.cisco.com/api/rest
+   description: APJ
+ - url: https://edge.aus.cdo.cisco.com/api/rest
+   description: AUS
+ - url: https://edge.in.cdo.cisco.com/api/rest
+   description: IN
+ - url: https://edge.staging.cdo.cisco.com/api/rest
+   description: Staging
+ - url: https://edge.scale.cdo.cisco.com/api/rest
+   description: Scale
+ - url: https://edge.ci.cdo.cisco.com/api/rest
+   description: CI
+securitySchemes:
+  bearerAuth:
+    type: http
+    scheme: bearer
+    bearerFormat: JWT

scripts/golang/.gitignore

@@ -0,0 +1,2 @@
+
+dist/

scripts/golang/.goreleaser.yaml

@@ -0,0 +1,60 @@
+# This is an example .goreleaser.yml file with some sensible defaults.
+# Make sure to check the documentation at https://goreleaser.com
+
+# The lines below are called `modelines`. See `:help modeline`
+# Feel free to remove those if you don't want/need to use them.
+# yaml-language-server: $schema=https://goreleaser.com/static/schema.json
+# vim: set ts=2 sw=2 tw=0 fo=cnqoj
+
+version: 1
+
+before:
+  hooks:
+    # You may remove this if you don't use go modules.
+    - go mod tidy
+    # you may remove this if you don't need go generate
+    - go generate ./...
+
+builds:
+  - env:
+      - CGO_ENABLED=0
+    goos:
+      - linux
+      - darwin
+    binary: cloud-fw-mgr-api-docs
+
+archives:
+  - format: tar.gz
+    # this name template makes the OS and Arch compatible with the results of `uname`.
+    name_template: >-
+      cloud-fw-mgr-api-docs_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    # use zip for windows archives
+    format_overrides:
+      - goos: windows
+        format: zip
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"
+
+nfpms:
+  -
+    id: cloud-fw-mgr-api-docs
+    package_name: cloud-fw-mgr-api-docs
+    section: default
+    priority: extra
+    maintainer: "CDO Ops <cdo.ops@cisco.com>"
+    formats:
+      - deb
+    description: |
+        Cloud Firewall Manager API Docs
+    vendor: "Cisco Systems"
+    homepage: "https://www.cisco.com"