eMASS API specification v3.12 implementation (#13)

mitre · Oct 10, 2023 · 91e4500 · 91e4500
1 parent f573672
commit 91e4500
Show file tree

Hide file tree

Showing 740 changed files with 42,392 additions and 25,457 deletions.
diff --git a/.github/workflows/generate-clients.yml b/.github/workflows/generate-clients.yml
@@ -4,7 +4,7 @@ on:
   push:
     branches: [ main ]
   # pull_request:
-  #   branches: [ V3_10_1 ]
+  #   branches: [ main ]
 
 jobs:
   generate-eMASS-clients:
@@ -14,14 +14,19 @@ jobs:
 
       # Checkout your code
       - name: Checkout 🛎️
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0  # OR "2" -> To retrieve the preceding commit.
 
-      # Check for changed files (looking for changes to the eMASSRestOpenApi.yaml file)
-      - name: Get changed files 🔧
+      # Check for changed files (looking for changes to the docs/eMASSRestOpenApi.yaml file)
+      - name: Get changed file (eMASSRestOpenApi.yaml)  🔧
         id: changed-files
-        uses: tj-actions/changed-files@v21
+        uses: tj-actions/changed-files@v39
+
+      - name: Run a step if eMASSRestOpenApi.yaml was modified
+        if: contains(steps.changed-files.outputs.modified_files, 'eMASSRestOpenApi.yaml')
+        run: |
+          echo "eMASSRestOpenApi.yaml file has been modified."
 
       # Use the action to generate a client package
       # This uses the default path for the openapi document and thus assumes there is an openapi.json in the current workspace.
@@ -31,7 +36,7 @@ jobs:
           generator: ruby
           config-file: src/openapi/templates/ruby/ruby-generator-config.json
           template-dir: src/openapi/templates/ruby
-          openapi-file: eMASSRestOpenApi.yaml
+          openapi-file: docs/eMASSRestOpenApi.yaml
         if: contains(steps.changed-files.outputs.modified_files, 'eMASSRestOpenApi.yaml')
 
       - name: Generate Typescript Client 🏭
@@ -40,7 +45,7 @@ jobs:
           generator: typescript-axios
           config-file: src/openapi/templates/typescript/typescript-generator-config.json
           template-dir: src/openapi/templates/typescript
-          openapi-file: eMASSRestOpenApi.yaml
+          openapi-file: docs/eMASSRestOpenApi.yaml
         if: contains(steps.changed-files.outputs.modified_files, 'eMASSRestOpenApi.yaml')
 
       - name: Generate Python Client 🏭
@@ -49,11 +54,11 @@ jobs:
           generator: python
           config-file: src/openapi/templates/python/python-generator-config.json
           template-dir: src/openapi/templates/python/mustache
-          openapi-file: eMASSRestOpenApi.yaml
+          openapi-file: docs/eMASSRestOpenApi.yaml
         if: contains(steps.changed-files.outputs.modified_files, 'eMASSRestOpenApi.yaml')
 
       # Publish the newly generated eMASS client to the current repo
-      - name: Publish Generated Clients 🚀
+      - name: Publish Generated Clients to GitHub 🚀
         if: contains(steps.changed-files.outputs.modified_files, 'eMASSRestOpenApi.yaml')
         env: 
           CI_COMMIT_MESSAGE: CI Build Client Artifacts (eMASS Clients)

diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml
@@ -13,20 +13,21 @@ jobs:
     name: Generate Document with redoc
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
-      # use the public name of the action
-      - name: redoc-cli test
-        uses: seeebiii/redoc-cli-github-action@v9
+      # Use redoc-cli-github-action to generate the HTML bundle
+      - name: Generate the HTML bumdle (redoc-cli)
+        uses: seeebiii/redoc-cli-github-action@v10
         with:
-          args: 'bundle eMASSRestOpenApi.yaml -o docs/redoc/index.html'
+          args: 'bundle docs/eMASSRestOpenApi.yaml -o docs/redoc/index.html'
 
       - name: check result
         run: |
           ls -al
           test -f docs/redoc/index.html || (echo "Fail to generate docs/redoc/index.html from previous step." && exit 1)
-
-      - name: deploy
+      
+      # Deploy static files to GitHub Pages
+      - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -12,7 +12,7 @@ jobs:
     name: Copy Markdown Files to gh_pages
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Build Deploment Folder 🔧
         run: |
@@ -25,7 +25,9 @@ jobs:
           sudo cp -R ./docs/redoc /publish/docs/redoc
           sudo cp -R ./docs/renderer /publish/docs/renderer
           sudo cp ./docs/developers.md /publish/docs/developers.md 
-             
+          sudo cp ./docs/eMASSRestOpenApi.yaml /publish/docs/eMASSRestOpenApi.yaml
+          sudo cp ./docs/eMASS_API_Documentation.pdf /publish/docs/eMASS_API_Documentation.pdf
+
       - name: Deploy Markdown Files 🚀
         uses: peaceiris/actions-gh-pages@v3
         with:

diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml
@@ -10,7 +10,7 @@ jobs:
     steps:
       - name: Setup ruby
         uses: actions/setup-ruby@v1
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - run: git fetch origin +refs/tags/*:refs/tags/*

diff --git a/.github/workflows/publish-npm-gpr.yml b/.github/workflows/publish-npm-gpr.yml
@@ -7,12 +7,12 @@ jobs:
   build-deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup node
         uses: actions/setup-node@v3
         with:
-          node-version: "16.x"
+          node-version: "18.x"
           registry-url: https://npm.pkg.github.com/
           scope: '@mitre'
 

diff --git a/.github/workflows/publish-npm-registry.yml b/.github/workflows/publish-npm-registry.yml
@@ -12,7 +12,7 @@ jobs:
       - name: Setup node
         uses: actions/setup-node@v3
         with:
-          node-version: "16.x"
+          node-version: "18.x"
           registry-url: 'https://registry.npmjs.org'
 
       - name: Build the NPM Package

diff --git a/.github/workflows/publish-to-pypi.yml b/.github/workflows/publish-to-pypi.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python
         uses: actions/setup-python@v4
         with:

diff --git a/.github/workflows/publish-to-test-pypi.yml b/.github/workflows/publish-to-test-pypi.yml
@@ -6,12 +6,16 @@ name: Publish Python 🐍 distributions 📦 to TestPyPI
 # 
 # For testing use:
 # on: push
-# (push to the TestPyPi registry on every push during development)
+#  NOTE:
+#   The workflow may fail the first time the clients are generate as it does not wait 
+#   for the [Generate OpenAPI Clients] to complete before it executes.
+#   Don't use final ver number when testing, it will fail when published based on the 
+#   workflows: [Generate OpenAPI Clients])
 #
 # Once test is completed use:
 # on:
 #   workflow_run:
-#     workflows: [Generate OpenAPI Clients] -> old ['generate-eMASS-clients']
+#     workflows: [Generate OpenAPI Clients]
 #      types:
 #        - completed
 #-----------------------------------------------------------------------------------
@@ -29,22 +33,34 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      # Checkout your code
+      - uses: actions/checkout@v4
+
+      # Check for changed files (looking for changes to the src/python_client/README.md) file)
+      - name: Get changed file (src/python_client/README.md)  🔧
+        id: changed-files
+        uses: tj-actions/changed-files@v39
+
+      # Only if the client version has changed
       - name: Set up Python
+        if: contains(steps.changed-files.outputs.modified_files, 'src/python_client/README.md')
         uses: actions/setup-python@v4
         with:
           python-version: "3.x"
 
       - name: Install pypa/build
+        if: contains(steps.changed-files.outputs.modified_files, 'src/python_client/README.md')
         run: |
           python -m pip install build --user
 
       - name: Build a binary wheel and a source tarball
+        if: contains(steps.changed-files.outputs.modified_files, 'src/python_client/README.md')
         run: |
           cd src/python_client
           python -m build --sdist --wheel --outdir dist/
       
       - name: Publish distribution 📦 to Test PyPI
+        if: contains(steps.changed-files.outputs.modified_files, 'src/python_client/README.md')
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           packages-dir: src/python_client/dist/

diff --git a/.github/workflows/test-ruby-client.yml b/.github/workflows/test-ruby-client.yml
@@ -3,8 +3,8 @@ name: Test Ruby Client
 on:
   push:
     branches: [ main ]
-  pull_request:
-    branches: [ main ]
+  # pull_request:
+  #   branches: [ main ]
 
 jobs:
   test:
@@ -20,7 +20,7 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby-version }}
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: crazy-max/ghaction-chocolatey@v1
         with:
           args: install curl -y

diff --git a/README.md b/README.md
@@ -5,16 +5,16 @@
 ![GitHub Release Date](https://img.shields.io/github/release-date/mitre/emass_client?label=Release%20Date&logo=github&color=blue) ![GitHub release (latest by date)](https://img.shields.io/github/v/release/mitre/emass_client?label=Release%20Version&logo=github) ![Gem](https://img.shields.io/gem/v/emass_client?label=gem%20version&logo=ruby&logoColor=red) ![npm](https://img.shields.io/npm/v/@mitre/emass_client?label=npm%20version&logo=npm) ![PyPI](https://img.shields.io/pypi/v/emass-client-api?label=pypi%20version&logo=pypi&logoColor=yellow)
 
 # eMASS Client
-The eMASS client repository (```emass_client```) maintains the Enterprise Mission Assurance Support Service (eMASS) Representational State Transfer (REST) Application Programming Interface (API) specifications and executables. The executables packages currently provided are: RubyGem and TypeScript Node.
+The eMASS client repository (```emass_client```) maintains the Enterprise Mission Assurance Support Service (eMASS) Representational State Transfer (REST) [Application Programming Interface (API) specifications](/docs/eMASS_API_Documentation.pdf) and executables. The executables packages currently provided are: RubyGem, TypeScript Node, and Python.
 
-***NOTE***: A CLI tool called [emasser](https://github.com/mitre/emasser), has been developed that makes use of the ```emass_client``` RubyGem.
+***NOTE***: A CLI tool called [emasser](https://github.com/mitre/emasser), has been developed that makes use of the ```emass_client``` RubyGem. Additionally, the [SAF CLI](https://github.com/mitre/saf#emass-api-cli) implements the `emass_client` npm package.
 
 # Highlights
 ## [eMASS API Specification](https://mitre.github.io/emass_client/docs/redoc/)
 The eMASS API is documented in YAML and can be viewed utilizing a multitude of visualization tools. Included is a dependency-free (and nice looking) rendering tool for viewing the API specification. The documentation is automatically generated using a Continuos Integration (CI) action [redoc-cli](https://www.npmjs.com/package/redoc-cli) command line tool.
 
 
-## [Visualize and Interact with eMASS API](https://mitre.github.io/emass_client/docs/renderer/)
+## [eMASS API Viewer](https://mitre.github.io/emass_client/docs/renderer/)
 This repository allows anyone to visualize and interact with the API’s resources without having any of the implementation logic in place, via [hosted](https://mitre.stoplight.io/docs/emasser/c48309f365cf1-enterprise-mission-assurance-support-service-e-mass) or local mock servers. Please reference [Developers Instruction](docs/developers.md) on how to setup a local mock server
 
 # eMASS API Clients Generation Process
@@ -28,42 +28,26 @@ The following ```emass_client``` executable packages are generated by this repos
 - Python - The python package is hosted and available in the [PyPIRegistry](https://pypi.org/manage/project/emass-client-api/releases/).
 
 ### Making Changes to eMASS Clients
-The most appropriate way to propose modifications or make changes to the eMASS clients generated in this repository is by [forking](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) this repository. 
+Changes to the eMASS clients are made by modifying the eMASS API specification file `eMASSRestOpenApi.yaml`. Modification to this file triggers the clients' generation actions where all client packages are generated, and published to the appropriate repositories when the PR branch is [merged](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) into the main branch.
 
-- Step 1
+After either forking or creating a branch for the main repository update the code via a pull request (PR) or directly on the branch.
 
-  [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) this repository 
-
-- Step 2 (optional)
+The proper process for making client code updates are as follows:
 
-  Create a new [branch](https://docs.github.com/en/get-started/quickstart/github-glossary#branch) to apply the modifications 
-
-- Step 3
-
-  [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) the newly create branch into the local machine
-
-- Step 4
+- **Step 1** 
+  Update the eMASS API specification file `eMASSRestOpenApi.yaml`
 
-  Make the necessary changes, modification locally
+- **Step 2**
+  Make the necessary changes (update the version field) to the clients generation configuration files:
+  - Ruby (src/openapi/templates/ruby/ruby-generator-config.json)
+  - Typescript(src/openapi/templates/typescript/typescript-generator-config.json)
+  - Python (src/openapi/templates/python/python-generator-config.json)
 
-  Ensure that the client(s) configuration file ```src/openapi/templates/[ruby or typescript]-generator-config.json``` reflect the correct version to be generated
-
-  **Note**: Modifications or updates to the eMASS API specification file ```eMASSRestOpenApi.yaml``` triggers the clients' generation actions; both the ruby gem ```src/ruby_client``` and typescript-axios npm ```src/typescript_client``` clients are re-generated and committed to the appropriate repositories when [merged](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) with the main branch.
-
-- Step 5
-
-  [Update](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) local changes to the forked 
+- **Step 3**
+  Push the content to the repository
 
-- Step 6
-
-  Create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests), this is where the changes are compared to the main branch of the forked repository
-
-- Step 7
-
-  Once the repository maintainer has approved a pull request, the updates in the forked or branch repository are merged with the main project repository.
-
-
-***NOTE***: The `emass_client` [GitHub Release](https://github.com/mitre/emass_client/releases) and the generated clients ([Ruby](https://rubygems.org/gems/emass_client) and [Typescript](https://www.npmjs.com/package/@mitre/emass_client)) version indicate what eMASS API version they implement. 
+- **Step 4**
+  Once all test pass merge the pull request
 
 
 ### Other Programming Languages

diff --git a/docs/developers.md b/docs/developers.md
@@ -1,13 +1,14 @@
 # Developers Instructions
 
-The documentation provided in this repository describes the eMASS REST API (v3.3) structure. It is an OpenAPI (v3.0.3) specification compliant describing and visualizing the eMASS RESTful API web services (endpoints).
+The documentation provided in this repository describes the eMASS REST API structure. It is an OpenAPI (v3.0.3) specification compliant describing and visualizing the eMASS RESTful API web services (endpoints).
 
 The API is documented in YAML and can be viewed utilizing Swagger Editor or Visual Studio Code (VSC) with swagger and yaml extensions.
 
 ## Visualizing 
 ### Viewing the API via Swagger
 
-There are online tool options for viewing and editing OpenAPI compliant RESTfull APIs like the eMASS API documentations. Some of these tools are Swagger Editor or SwaggerHub. <strong>We discourage the utilization of any online capability for editing a controlled unclassified API document</strong>.
+There are online tool options for viewing and editing OpenAPI compliant RESTfull APIs like the eMASS API documentations. Some of these tools are Swagger Editor or SwaggerHub. 
+
 
 ***Note***: We recommend utilizing the instruction provided here for viewing or editing the eMASS API.
 
@@ -56,7 +57,7 @@ prism mock -d -p 4010 eMASSRestOpenAPI.yaml
 * If using VSC, Prism restarts automatically when the yaml file is modified and saved
 * Use `npx` instead of `npm` to install packages locally, but still be able to run them as if they were global
 
-Now you can access the fake API endpoints utilizing either CURL or the Swagger Editor. The following curl command invokes the systems endpoint with a path parameter of policy=rmf:
+Now you can access the mock API endpoints utilizing either CURL or the Swagger Editor. The following curl command invokes the systems endpoint with a path parameter of policy=rmf:
 ``` node
 curl -X GET "http://localhost:4010/api/systems?policy=rmf" -H  "accept: application/json" -H  "api-key: f32516cc-57d3-43f5-9e16-8f86780a4cce" -H  "user-uid: 1647389405"
 ```
@@ -68,6 +69,8 @@ The API clients are generated utilizing the [OpenAPI Generator](https://github.c
 **Note:** Currently there are three (3) client SDKs (ruby, typscript-axios, and python) that are automatically generated utilizing GitHub action implemented within this repository. They are generated when a push to the main branch occurs and the API specification file has been modified.
 
 ### Generate an eMASS Client
+
+#### Using Java executables
 Follow these steps to generate an eMASS client for additional supported language provided by the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) CLI:
 - Step 1
 
@@ -123,7 +126,22 @@ Follow these steps to generate an eMASS client for additional supported language
   openapi-generators/openapitools-generator-action@v1
   ```
 
-An OpenAPI Generator CLI Docker Image solution is available and documented [here](https://github.com/OpenAPITools/openapi-generator#16---docker) as a Public Pre-built Docker image.
+#### Using Docker 
+An OpenAPI Generator CLI Docker Image solution is available and documented here as a [Public Pre-built Docker image](https://github.com/OpenAPITools/openapi-generator#16---docker).
+
+Available options are:
+
+- Use the official CLI
+    ```
+    docker pull openapitools/openapi-generator-cli
+    ```
+ - Run openapi-generator as a web service
+    ```
+    docker pull openapitools/openapi-generator-online
+    docker run -d -e GENERATOR_HOST=http://12.34.56.78 -p 80:8080 openapitools/openapi-generator-online
+    ```
+      (where 12.34.56.78 is your server IP address)
+
 
 ---