clarify Duration minutes indefinite is 0

.github/workflows/golangci-lint.yml

@@ -11,7 +11,7 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: actions/setup-go@v3
         with:

.github/workflows/main.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Git Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           persist-credentials: false
 

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-# Code of Conduct
-
-All open source projects managed by OpenZiti share a common [code of conduct](https://docs.openziti.io/policies/CODE_OF_CONDUCT.html) 
-which all contributors are expected to follow. Please be sure you read, understand and adhere to the guidelines expressed therein.
+# Code of Conduct
+
+All open source projects managed by OpenZiti share a common [code of conduct](https://docs.openziti.io/policies/CODE_OF_CONDUCT.html) 
+which all contributors are expected to follow. Please be sure you read, understand and adhere to the guidelines expressed therein.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing
-
-NetFoundry welcomes all and any contributions. All open source projects managed by NetFoundry share a common
-[guide for contributions](https://docs.openziti.io/policies/CONTRIBUTING.html).
-
-If you are eager to contribute to a NetFoundry-managed open source project please read and act accordingly.
+# Contributing
+
+NetFoundry welcomes all and any contributions. All open source projects managed by NetFoundry share a common
+[guide for contributions](https://docs.openziti.io/policies/CONTRIBUTING.html).
+
+If you are eager to contribute to a NetFoundry-managed open source project please read and act accordingly.

README.md

@@ -3,43 +3,86 @@
 This repository contains the Open API 2.0 specification for the OpenZiti Edge Client and Management REST APIs. It also
 contains a generated go module, in the `rest_*` directories that can be used to develop against OpenZiti Controllers.
 
-# Versioning
+## Versioning
 
-Versioning of the APIs in this repository are independent of the OpenZiti releases created in the 
-[`ziti`](https://github.com/openziti/zit) repository. Many versions of these API specifications are  compatible with 
+Versioning of the APIs in this repository is independent of the OpenZiti releases created in the
+[`ziti`](https://github.com/openziti/zit) repository. Many versions of these API specifications are compatible with
 multiple versions of the OpenZiti release versions. To make it somewhat intuitive, the minor version number of the API
-is the *minimum minor version of the `ziti`* repository releases that this API is compatible with. It will also be 
+is the *minimum minor version of the `ziti`* repository releases that this API is compatible with. It will also be
 compatible up until the next minor version of the specifications. Patch versions are used for internal fixes and release
 tags.
 
-For simplicity each controller hosts the specification version they expect and may be used instead of this repository
+For simplicity, each controller hosts the specification version they expect and may be used instead of this repository
 for live deployments.
 
-# Client & Server Generation
+## Client & Server Generation
 
-The root level `client.yml` and `management.yml` files are generated from the `source` directory. There are scripts
-within the `script` directory that will do the heavy lifting of re-generating them if needed.Both scripts require
-that the `swagger` executable be available on your `path` environment variable. Releases of it are available in the
-[GitHub Go-Swagger](https://github.com/go-swagger/go-swagger/releases) repository. Avoid release 0.30 for now because
-it has a bug. 0.29 works.
+The root-level `client.yml` and `management.yml` OpenAPI 2.0 specification  files are generated from the `source`
+directory. There are scripts in `./scripts/` for re-generating these specifications and the Go client and server
+libraries. The scripts require that a specific build of the `swagger` (aka "go-swagger") executable.
+[Download the Go-Swagger v0.29.0 binary](https://github.com/go-swagger/go-swagger/releases/tag/v0.29.0) from GitHub.
+
+Do not `go install` the binary because the rendering may introduce whitespace changes in many files.
+
+### Modify the Specification Sources
+
+These files are used to build the specifications.
 
 ```bash
-#bash
-./scripts/generate_rest.sh
+./source
+├── client
+├── client.yml
+├── management
+├── management.yml
+└── shared
 ```
 
+### Bump the Specification Version
+
+Update the version numbers in `./source/client.yml` and `./source/management.yml` in your PR. The versions must be identical.
+
+### Prepare the Local Filesystem
+
+You must clone two repos in adjacent directories.
+
+1. this repo - https://github.com/openziti/edge-api.git
+1. the main ziti repo - https://github.com/openziti/ziti.git
+
+### Generate the Specifications and Test
+
+You must create a workspace for the main repo (`ziti`) to run tests against the checkout in this repo (`edge-api`).
+
+#### Linux/Darwin Example
+
+```bash
+(
+    set -euxo pipefail;
+    ./scripts/generate_rest.sh;
+    (
+        cd ../ziti;
+        [[ -s ./go.work ]] && mv -v ./go.work{,.$(date --utc --iso-8601=seconds)};
+        go work init;
+        go work use .;
+        go work use ../edge-api;
+        go test ./... -tags apitests;
+    )
+)
+```
+
+#### Windows Example
+
 ```powershell
 #powershell
 ./scripts/generate_rest.ps1
 ```
 
-# Using the generated go module
+## Using the generated go module
 
-Within the go module within the `go` directory is a submodule named `rest_util` with contains helper functions for using
+Within the go module within the `go` directory is a submodule named `rest_util` containing helper functions for using
 its sibling `*_client` submodules. This package is not generated. See `rest_util/examples` for full examples.
 
-
 Example:
+
 ```go
 func main() {
 	ctrlAddress := "https://localhost:1280"

client.yml

@@ -15,7 +15,7 @@ info:
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: 0.26.25
+  version: 0.26.26
 host: demo.ziti.dev
 basePath: /edge/client/v1
 paths:

management.yml

@@ -15,7 +15,7 @@ info:
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
-  version: 0.26.25
+  version: 0.26.26
 host: demo.ziti.dev
 basePath: /edge/management/v1
 paths:
@@ -8558,7 +8558,7 @@ paths:
       - oauth2:
         - openid
       description: |
-        Allows an admin disable an identity for a set amount of time or indefinitely.
+        Reject an identity's API session requests for N minutes or indefinitely if 0.
       tags:
       - Identity
       summary: Set an identity as disabled

scripts/generate_rest.sh

@@ -1,11 +1,28 @@
-#!/bin/bash -e
+#!/usr/bin/env bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+GO_SWAGGER_VERSION="v0.29.0"
+GO_SWAGGER_HASH="09ae1192ca9a941bbb534aca09e6bdc562c95ef3"
+if ! command -v swagger &>/dev/null \
+|| [[ "$(swagger version | awk '$1~/^version:/{print $2}')" != "${GO_SWAGGER_VERSION}" \
+|| "$(swagger version | awk '$1~/^commit:/{print $2}')" != "${GO_SWAGGER_HASH}" ]]
+then
+  echo >&2 "Go Swagger executable 'swagger' ${GO_SWAGGER_VERSION} (${GO_SWAGGER_HASH}) is required. Download the binary from GitHub: https://github.com/go-swagger/go-swagger/releases/tag/v0.29.0"
+  exit 1
+fi
 
-command -v swagger >/dev/null 2>&1 || {
-  echo >&2 "Command 'swagger' not installed. See: https://github.com/go-swagger/go-swagger for installation"
+if GO_VERSION="$(go version | awk '{print $3}')"
+then
+  echo "Using go toolchain version: ${GO_VERSION}"
+else
+  echo >&2 "Failed to determine go toolchain version"
   exit 1
-}
+fi
 
-scriptPath=$(realpath $0)
+scriptPath=$(realpath "$0")
 scriptDir=$(dirname "$scriptPath")
 
 rootDir=$(realpath "$scriptDir/..")
@@ -85,8 +102,8 @@ fi
 
 echo "...fixing go module deps"
 prev=$(pwd)
-cd $codeTarget
+cd "$codeTarget"
 go mod init github.com/openziti/edge-api || true
 go get -u ./...
 go mod tidy
-cd $prev
+cd "$prev"

source/client.yml

@@ -1,7 +1,7 @@
 ---
 swagger: '2.0'
 info:
-  version: 0.26.25
+  version: 0.26.26
   title: Ziti Edge Client
   description: OpenZiti Edge Client API
   contact:

source/management.yml

@@ -1,7 +1,7 @@
 ---
 swagger: '2.0'
 info:
-  version: 0.26.25
+  version: 0.26.26
   title: Ziti Edge Management
   description: OpenZiti Edge Management API
   contact:

source/management/identities.yml

@@ -531,7 +531,7 @@ paths:
     post:
       summary: Set an identity as disabled
       description: |
-        Allows an admin disable an identity for a set amount of time or indefinitely.
+        Reject an identity's API session requests for N minutes or indefinitely if 0.
       security:
         - ztSession: [ ]
         - oauth2: [ openid ]