Skip to content

Commit

Permalink
eMASS API specification v3.12 implementation (#13)
Browse files Browse the repository at this point in the history
  • Loading branch information
georgedias authored Oct 10, 2023
1 parent f573672 commit 91e4500
Show file tree
Hide file tree
Showing 740 changed files with 42,392 additions and 25,457 deletions.
23 changes: 14 additions & 9 deletions .github/workflows/generate-clients.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ on:
push:
branches: [ main ]
# pull_request:
# branches: [ V3_10_1 ]
# branches: [ main ]

jobs:
generate-eMASS-clients:
Expand All @@ -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.
Expand All @@ -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 🏭
Expand All @@ -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 🏭
Expand All @@ -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)
Expand Down
15 changes: 8 additions & 7 deletions .github/workflows/generate_docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
Expand Down
6 changes: 4 additions & 2 deletions .github/workflows/gh-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish-gem.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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/*
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/publish-npm-gpr.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish-npm-registry.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish-to-pypi.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
22 changes: 19 additions & 3 deletions .github/workflows/publish-to-test-pypi.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
#-----------------------------------------------------------------------------------
Expand All @@ -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/
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/test-ruby-client.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ name: Test Ruby Client
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
# pull_request:
# branches: [ main ]

jobs:
test:
Expand All @@ -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
Expand Down
50 changes: 17 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
26 changes: 22 additions & 4 deletions docs/developers.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down Expand Up @@ -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"
```
Expand All @@ -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

Expand Down Expand Up @@ -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)


---

Expand Down
Loading

0 comments on commit 91e4500

Please sign in to comment.