diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index dcd7fdd1..39986637 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -12,8 +12,8 @@ name: "CodeQL" on: - # push: - # branches: [ main ] + push: + branches: [ main ] pull_request: # The branches below must be a subset of the branches above branches: [ main ] diff --git a/.github/workflows/generate_docs.yml b/.github/workflows/generate_docs.yml index 36f5fd7d..7f48fb4d 100644 --- a/.github/workflows/generate_docs.yml +++ b/.github/workflows/generate_docs.yml @@ -2,8 +2,8 @@ name: Generate eMASS Documentation # Run on each push to main on: - # push: - # branches: [ main ] + push: + branches: [ main ] pull_request: branches: [ main ] jobs: diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 9222464f..712786de 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -1,7 +1,7 @@ name: Deploy to GitHub Pages on: - # push: - # branches: [ main ] + push: + branches: [ main ] pull_request: branches: [ main ] diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml new file mode 100644 index 00000000..fbb9bcce --- /dev/null +++ b/.github/workflows/publish-gem.yml @@ -0,0 +1,38 @@ +name: Build and release gem + +on: + release: + types: [published] + +jobs: + release: + name: Release to gem hosts + runs-on: ubuntu-latest + steps: + - name: Setup ruby + uses: actions/setup-ruby@v1 + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + - run: git fetch origin +refs/tags/*:refs/tags/* + - name: Setup credentials and versioning + run: | + gem install keycutter + mkdir -p $HOME/.gem + touch $HOME/.gem/credentials + chmod 0600 $HOME/.gem/credentials + printf -- "---\n:rubygems_api_key: ${RUBYGEMS_API_KEY}\n" > $HOME/.gem/credentials + printf -- ":github: Bearer ${GPR_API_KEY}\n" >> $HOME/.gem/credentials + env: + RUBYGEMS_API_KEY: ${{secrets.RUBYGEMS_AUTH_TOKEN}} + GPR_API_KEY: ${{secrets.GITHUB_TOKEN}} + - name: Build emass_client + run: gem build -C src/ruby_client/ emass_client.gemspec + - name: Publish to RubyGems + run: | + gem push --KEY rubygems --host https://rubygems.org src/ruby_client/*.gem + - name: Publish to GPR + run: | + gem push --KEY github --host https://rubygems.pkg.github.com/mitre src/ruby_client/*.gem + env: + OWNER: mitre diff --git a/.github/workflows/test-ruby-client.yml b/.github/workflows/test-ruby-client.yml index 68c41186..8f9168c5 100644 --- a/.github/workflows/test-ruby-client.yml +++ b/.github/workflows/test-ruby-client.yml @@ -1,8 +1,8 @@ name: Test Ruby Client on: - # push: - # branches: [ main ] + push: + branches: [ main ] pull_request: branches: [ main ] diff --git a/docs/developers.md b/docs/developers.md index 6945e9ab..dd79a9c9 100644 --- a/docs/developers.md +++ b/docs/developers.md @@ -1,12 +1,9 @@ # Developers Instructions -The documentation provided here is an OpenAPI (v3.0.3) Specification compliant describing, producing, consuming, and visualizing the eMASS RESTful API web services (endpoints) as described in the eMASS REST API (v3.2) document, dated October 21, 2021. +The documentation provided here is an OpenAPI (v3.0.3) Specification compliant describing, producing, consuming, and visualizing the eMASS RESTful API web services (endpoints) as described by the eMASS REST API (v3.3) document, dated March 26, 2022. The API is documented in YAML and can be viewed utilizing Swagger Editor or Visual Studio Code (VSC) with swagger and yaml extensions. -The API clients are generated utilizing the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) CLI. - - ### 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. We discourage the utilization of any online capability for editing a controlled unclassified API document. @@ -14,9 +11,9 @@ There are online tool options for viewing and editing OpenAPI compliant RESTfull To install the Swagger Editor offline from its repository follow these [instructions](https://github.com/swagger-api/swagger-editor). ### Generate the API documentation (to view in a web browser-html) -eMASS API documentation can be found [here](/docs/redoc/index.html) +eMASS API documentation can be found [here](https://mitre.github.io/emass_client/docs/redoc/) -To generate the API documentation that can be viewable in a totally dependency-free (and nice looking) HTML use the `redoc-cli` command line tool. +To generate the API documentation, viewable on a dependency-free (and nice looking) HTML use the `redoc-cli` command line tool. Install the tool via `npm`: @@ -28,7 +25,7 @@ To generate the HTML document, use the following command: redoc-cli bundle -o ./output/eMASS.html eMASSRestOpenApi.yaml ``` -The command above assumes that the generated file is placed in a subfolder relative to the current folder called output, and that the eMASSRestApi.yaml is in the current working directory. The generated file is called eMASS.html and can be viewed in any web browser. +The command above places the generated HTML file (eMASS.html) in a subfolder called output. The command assumes that the eMASSRestApi.yaml is in the current working directory. The generated file can be viewed in any web browser. ### Setting up Visual Studio Code Install these Extensions (Ctrl+Shift+X): @@ -67,39 +64,10 @@ curl -X GET "http://localhost:4010/api/systems?policy=rmf" -H "accept: applicat ``` Note: The API expects the api-key and user-uid headers. -## Swagger Codegen -### Clone the source code -Follow these instruction to generate the eMASS client API library (software development kit - SDK): -``` git -git clone https://github.com/swagger-api/swagger-codegen -cd swagger-codegen -git checkout 3.0.0 -mvn clean package -``` -Alternatively, you can follow instruction listed in [Swagger Codegen](https://github.com/swagger-api/swagger-codegen/tree/3.0.0#getting-started). The eMASS API utilized the OpenAPI version 3.0 standards, ensure that the proper `Swagger Codegen` is utilized to generate the client SDK. - - ### Build the Client SDK +The API clients are generated utilizing the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) CLI. -NOTE: The current [handlebar templates](https://github.com/swagger-api/swagger-codegen/tree/3.0.0#modifying-the-client-library-format) do not provide a configuration variable where a keypassword can be defined containing the client certificate passphrase used by libcurl wrapper Typhoeus. For this reason, we have provided [updated templates](./swagger-codegen/ruby_template) that can be utilized in the interim until the necessary fixes are integrated into the [main repository](https://github.com/swagger-api/swagger-codegen/tree/3.0.0) - -After cloning the appropriate `Swagger Codegen` baseline (3.0.0) generate the SDK (make sure you are in the cloned directory, e.g; /path/to/codegen/swagger-codegen) - -To generate the client SDK with provided templates use: -``` node -java -jar swagger-codegen-cli generate generate -i /path/to/yaml/eMASSRestOpenApi.yaml -l ruby -t emass_client/swagger-codegen/ruby_template -o /path/to/sdk/emass_api_client -``` - - -To generate without specifying the templates use: -``` node -java -jar swagger-codegen-cli generate -i /path/to/yaml/eMASSRestOpenApi.yaml -l ruby -o /path/to/sdk/emass_api_client -``` -Note: The command listed above is for generating a ruby client SDK. Other languages are available, see instructions [here](https://github.com/swagger-api/swagger-codegen/tree/3.0.0#to-generate-a-sample-client-library) - -## Ruby Client -Information about the swagger generated ruby client SDK refer to the [ruby_client](./ruby_client) directory. - +**Note:** Currently there are two (2) client SDKs (ruby, and typscript-axios) that are automatically generated utilizing the GitHub action implemented within this repository. The are generated when a push to main occurs and the API specification files has been modified. ---