From 8024bc896962cf78e10007422f19a94765113f67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Si=C3=B4n=20le=20Roux?= Date: Fri, 12 Jul 2024 13:14:39 +0200 Subject: [PATCH 1/5] Add optional workspace-dir input to set where the generation script runs Running the script from the repo root works fine if your OpenAPI spec is all in one file, but if it is in separate files it fails because the main schema references them relative to itself but the script is looking for them relative to the directory it's running in, which is not necessarily the same. For example, if the schemas are in schemas.json and you include it in the main file with a file reference and their both in a docs/ directory, you'll get an error like this: Invalid JSON pointer: ./schemas.json#/components/schemas/something You can solve this by moving all the OpenAPI files to the root of the repository where the script is run from but that clutters the repo root. Alternatively you can run the script from the directory the files are in so that the relative paths are correct. For this second option users need to be able to specify a directory relative to the repo root as the base path for the OpenAPI schemas if their spec is structured this way. The new, optional, input `workspace-dir` will be appended to the `github.workspace` path when setting the `WORKSPACE_DIR` environment variable that the generation script is already using. This way the script will go that directory instead of the repo root and it'll be able to find the referenced files. --- README.md | 1 + action.yml | 7 +++++-- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9688bfc..8997277 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ Add the following steps to your GitHub workflow, replacing the input values: ] # Parent directory to use for generated API docs HTML api-docs-dir: 'YOUR_API_DOCS_FILEPATH' + workspace-dir: 'OPTIONAL_RELATIVE_PATH_TO_THE_OPENAPI_SCHEMA' ``` ## Scenarios diff --git a/action.yml b/action.yml index bcb6c7a..d84f1e7 100644 --- a/action.yml +++ b/action.yml @@ -12,6 +12,9 @@ inputs: api-docs-dir: description: Parent directory to use for API docs required: true + workspace-dir: + description: Optional directory to run the generation script from + required: false # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. @@ -55,8 +58,8 @@ runs: GH_ACTION_REPOSITORY: ${{ github.action_repository || github.repository }} # Required to pass permissions to fetch OpenAPI spec files from Git branches GH_TOKEN: ${{ github.token }} - # Used to return to caller's repository directory - WORKSPACE_DIR: ${{ github.workspace }} + # Used to return to caller's repository directory (relative workspace-dir is appended if provided) + WORKSPACE_DIR: ${{ join([github.workspace, inputs.workspace-dir], '/') }} - name: Set up GitHub Pages uses: actions/configure-pages@v5 - name: Upload API docs to GitHub Pages From 54ae627e522312763727e8bdfd6688154133afa9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Si=C3=B4n=20le=20Roux?= Date: Mon, 15 Jul 2024 14:11:32 +0200 Subject: [PATCH 2/5] Replace join expression with format The join expression expects an array as input but it's not clear how you can make an array yourself during the script, it seems to only support ones that are made for you by the runtime. Format supports arbitrary input though, so it should work. A trailing or double slash shouldn't matter if the underlying FS is Linux-like. --- action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/action.yml b/action.yml index d84f1e7..f3aeb32 100644 --- a/action.yml +++ b/action.yml @@ -59,7 +59,7 @@ runs: # Required to pass permissions to fetch OpenAPI spec files from Git branches GH_TOKEN: ${{ github.token }} # Used to return to caller's repository directory (relative workspace-dir is appended if provided) - WORKSPACE_DIR: ${{ join([github.workspace, inputs.workspace-dir], '/') }} + WORKSPACE_DIR: ${{ format('{0}/{1}', github.workspace, inputs.workspace-dir) }} - name: Set up GitHub Pages uses: actions/configure-pages@v5 - name: Upload API docs to GitHub Pages From af3df47166667323baf720c086270ecf7828f656 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Si=C3=B4n=20le=20Roux?= Date: Tue, 16 Jul 2024 07:57:18 +0200 Subject: [PATCH 3/5] Add new SRC_DIR var instead of trying to re-use WORKSPACE_DIR If WORKSPACE_DIR isn't the repo root then at the end the next actions can't find the generated files to publish to GitHub pages. --- action.yml | 8 +++++--- scripts/generate-single-spec-doc.sh | 4 ++++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/action.yml b/action.yml index f3aeb32..03c0e3e 100644 --- a/action.yml +++ b/action.yml @@ -12,7 +12,7 @@ inputs: api-docs-dir: description: Parent directory to use for API docs required: true - workspace-dir: + src-dir: description: Optional directory to run the generation script from required: false @@ -58,8 +58,10 @@ runs: GH_ACTION_REPOSITORY: ${{ github.action_repository || github.repository }} # Required to pass permissions to fetch OpenAPI spec files from Git branches GH_TOKEN: ${{ github.token }} - # Used to return to caller's repository directory (relative workspace-dir is appended if provided) - WORKSPACE_DIR: ${{ format('{0}/{1}', github.workspace, inputs.workspace-dir) }} + # Used to return to caller's repository directory + WORKSPACE_DIR: ${{ github.workspace }} + # Used for multi-file API specs, run the script from this directory to correctly resolve relative paths in references + SRC_DIR: ${{ inputs.src-dir) }} - name: Set up GitHub Pages uses: actions/configure-pages@v5 - name: Upload API docs to GitHub Pages diff --git a/scripts/generate-single-spec-doc.sh b/scripts/generate-single-spec-doc.sh index fbc51db..b8b7c40 100644 --- a/scripts/generate-single-spec-doc.sh +++ b/scripts/generate-single-spec-doc.sh @@ -76,6 +76,10 @@ fullyQualifiedApiFilepath="$WORKSPACE_DIR/$API_DOCS_DIR/$apiDocFilepath" apiFileDir=$(dirname $fullyQualifiedApiFilepath) mkdir -p $apiFileDir echo "Generating ReDoc API docs at $fullyQualifiedApiFilepath" +if [ -n "$SRC_DIR" ]; then + echo "Changing directory to SRC_DIR: $SRC_DIR" + cd "${SRC_DIR}" +fi npx @redocly/cli build-docs $openApiYamlFilepath -o $fullyQualifiedApiFilepath if [ ! -f "$fullyQualifiedApiFilepath" ]; then From d4622988273ec239b0ef9bb07f21ff5c1ba683ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Si=C3=B4n=20le=20Roux?= Date: Tue, 16 Jul 2024 08:12:14 +0200 Subject: [PATCH 4/5] Fixed a lame typo --- action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/action.yml b/action.yml index 03c0e3e..2c4560b 100644 --- a/action.yml +++ b/action.yml @@ -61,7 +61,7 @@ runs: # Used to return to caller's repository directory WORKSPACE_DIR: ${{ github.workspace }} # Used for multi-file API specs, run the script from this directory to correctly resolve relative paths in references - SRC_DIR: ${{ inputs.src-dir) }} + SRC_DIR: ${{ inputs.src-dir }} - name: Set up GitHub Pages uses: actions/configure-pages@v5 - name: Upload API docs to GitHub Pages From 4f4556605030325b912b7b3d774610089049d07a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Si=C3=B4n=20le=20Roux?= Date: Tue, 16 Jul 2024 08:18:11 +0200 Subject: [PATCH 5/5] Change to SRC_DIR earlier (before API spec file check) --- scripts/generate-single-spec-doc.sh | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/scripts/generate-single-spec-doc.sh b/scripts/generate-single-spec-doc.sh index b8b7c40..b2e31d8 100644 --- a/scripts/generate-single-spec-doc.sh +++ b/scripts/generate-single-spec-doc.sh @@ -56,6 +56,12 @@ else $apiSpecFetchUri > $openApiJsonFilepath fi +# Go to the source directory if provided +if [ -n "$SRC_DIR" ]; then + echo "Changing directory to SRC_DIR: $SRC_DIR" + cd "${SRC_DIR}" +fi + # Validate OpenAPI JSON spec exists if [ ! -f "$openApiJsonFilepath" ]; then echo "Failed to generate API documentation since API spec was not found at $openApiJsonFilepath" @@ -76,10 +82,6 @@ fullyQualifiedApiFilepath="$WORKSPACE_DIR/$API_DOCS_DIR/$apiDocFilepath" apiFileDir=$(dirname $fullyQualifiedApiFilepath) mkdir -p $apiFileDir echo "Generating ReDoc API docs at $fullyQualifiedApiFilepath" -if [ -n "$SRC_DIR" ]; then - echo "Changing directory to SRC_DIR: $SRC_DIR" - cd "${SRC_DIR}" -fi npx @redocly/cli build-docs $openApiYamlFilepath -o $fullyQualifiedApiFilepath if [ ! -f "$fullyQualifiedApiFilepath" ]; then