Skip to content

Commit

Permalink
Readme changes (#35)
Browse files Browse the repository at this point in the history 
* Readme changes

* changes
  • Loading branch information
@NiraimathiGunalan
NiraimathiGunalan authored Jun 12, 2024
1 parent 511791b commit ae33e2b
Showing 1 changed file with 28 additions and 28 deletions.
56 changes: 28 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Create a Apiconnect Discovery Action
# Create an APIConnect Discovery Action

The Apiconnect Discovery Action allows you to send and keep in sync your OpenAPI reference documents with Apiconnect.
The action will sync the documents with the discovery service repository in Apiconnect and from there they can be promoted
as required to be managed by Apiconnect through their entire lifecycle.
The APIConnect Discovery Action allows you to send and keep in sync your OpenAPI reference documents with APIConnect.
The action will sync the documents with the discovery service repository in APIConnect and from there they can be promoted
as required to be managed by APIConnect through their entire lifecycle.

# Usage

Expand All @@ -12,29 +12,29 @@ See [action.yml](action.yml)

The following parameters are always required:

- API_HOST - Domain name of the ApiConnect instance where discovered APIs will be sent.<br /> &nbsp; Example : `us-east.apiconnect.automation.ibm.com`
- PLATFORM_API_PREFIX - Platform API prefix has a default value of `platform-api` which is the same as the prefix value for ApiConnect on Cloud. It can be changed to match your systems set up if different from the default
- INSECURE_SKIP_TLS_VERIFY - If set to true the action skips the validity check for the server's certificate. This may be required in the case where your APIConnect system is using self signed certificates. Note: Setting this will make your HTTPS connections insecure.
- PROVIDER_ORG - The provider org name of the apiconnect manager
- API_FILES - One or more file names of the APIs to sync with apiconnect discovery repo separated by comma.<br /> &nbsp; Example : `gmail-api.json,gmail-api.yaml,mit-api.json,APIfolder/petstore-exp.json`
- API_FOLDERS - One or more folder names containing APIs to sync with apiconnect discovery repo separated by comma. <br /> &nbsp; Example : `APIFiles,APIFolders`
- resync_check: Indicates if changes to the action like at initial creation should trigger a api-file sync.
- git_diff: (Optional) Git diff between the current and the previous commit. If multiple files have changed in the commit then the workflow will run only if one of the files supplied in `API_FILES` or `API_FOLDERS` has changed.
- apikey - An API Key can be obtained from the api-manager for the user who has access to post the API.<br />
An API key can be created by logging into the APIC Manager UI and selecting the "My API Keys" option under the profile icon from the top navigation bar. It is good practice to store any sensitive data like the apikey as a github action secret. See [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for more details. For the sample below the github secret should be called `apicApikey` as it will need to match the following templated value
${{ secrets.apicApikey }}

The format of the API documents can be json or yaml. Among the parameters used, either `API_FILES` or `API_FOLDERS` needs to be supplied according to how the API documents are sent. The APIs can be sent to the API connect discovery service in any one of the following ways - single/multiple documents or folder/folders with APIs documents in it. Single and multiple documents will be supplied through `API_FILES` param and single and multiple folders with many API files inside will be supplied through `API_FOLDERS` param.<br />
- API_HOST - Domain name of the APIConnect instance where discovered APIs will be sent.<br /> &nbsp; Example : `us-east.apiconnect.automation.ibm.com`
- PLATFORM_API_PREFIX - The Platform API prefix has a default value of `platform-api`, the same as the prefix value for APIConnect on Cloud. It can be changed to match your system setup if it is different from the default
- INSECURE_SKIP_TLS_VERIFY - If set to true the action skips the validity check for the server's certificate. This may be required in the case where your APIConnect system is using self-signed certificates. Note: Setting this will make your HTTPS connections insecure.
- PROVIDER_ORG - The provider org name of the APIConnect manager.
- API_FILES - One or more file names of the APIs to sync with the APIConnect discovery repo separated by a comma.<br /> &nbsp; Example : `gmail-api.json,gmail-api.yaml,mit-api.json,APIfolder/petstore-exp.json`
- API_FOLDERS - One or more folder names containing APIs to sync with the APIConnect discovery repo separated by a comma. <br /> &nbsp; Example: `APIFiles, APIFolders`
- resync_check: Indicates if changes to the action like at initial creation should trigger an api-file sync.
- git_diff: (Optional) Git diff between the current and the previous commit. If multiple files have changed in the commit, the workflow will run only if one of the files supplied in `API_FILES` or `API_FOLDERS` has changed.
- apikey - An API Key can be obtained from the APIConnect manager for the user who has access to post the API.<br />
An API key can be created by logging into the APIConnect Manager UI and selecting the "My API Keys" option under the profile icon from the top navigation bar. It is good practice to store any sensitive data like the apikey as a GitHub action secret. See [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for more details. For the sample below the GitHub secret should be called `apicApikey` as it will need to match the following templated value  
${{ secrets.apicApikey }} 

The format of the API documents can be json or yaml. Among the parameters used, either `API_FILES` or `API_FOLDERS` must be supplied according to how the API documents are sent. The APIs can be sent to the APIConnect discovery service in any one of the following ways - single/multiple documents or folder/folders with APIs documents in it. Single and multiple documents will be supplied through the `API_FILES` param and single and multiple folders with many API files inside will be supplied through the `API_FOLDERS` param.<br />
To send the documents, create the workflow in your GitHub repository similar to one of the samples below

To create the workflow action in your github repository do the following
To create the workflow action in your GitHub repository do the following
1. Create a .github/workflows directory in your repository on GitHub if this directory does not already exist.
2. In the .github/workflows directory, create a file named **discover-api.yml**.
3. Copy the yaml contents of any one of the example described below into the discover-api.yml file.
3. Copy the yaml contents of any examples described below into the discover-api.yml file.
4. Update the env variables and secret to match your environment.

```
name: Sync Discovered API with ApiConnect
name: Sync Discovered API with APIConnect
on: [pull_request, workflow_dispatch, push]
Expand Down Expand Up @@ -73,12 +73,12 @@ jobs:
```

In the above yml content, env and jobs are described to send API documents.<br />
The job works as follows, on a push commit to the github repo the specified `api_files` will be sent to the discovery service repo of the given `provider_org` at location `api_host` using the `api_key` to authenticate with the discovery service.<br />
The job will send the git diff of the files between the previous commit and the current commit and the discovery action will verify whether any of the changed files include files supplied in `API_FILES` or `API_FOLDERS`.<br />
`API_FILES` can be replaced with `API_FOLDERS` when the entire folder/folders needs to be sent. This can be used when the git push has multiple files and needs to run the workflow when any of the supplied file changed.
The job works as follows, on a push commit to the GitHub repo the specified `api_files` will be sent to the discovery service repo of the given `provider_org` at location `api_host` using the `api_key` to authenticate with the discovery service.<br />
The job will send the git diff of the files between the previous commit and the current commit and the discovery action will verify whether any of the changed files include files supplied in `API_FILES` or `API_FOLDERS`.<br />
`API_FILES` can be replaced with `API_FOLDERS` when the entire folder/folders needs to be sent. This can be used when the git push has multiple files and needs to run the workflow when any of the supplied files changes.

```
name: Sync Discovered API with ApiConnect
name: Sync Discovered API with APIConnect
on: [pull_request, workflow_dispatch, push]
Expand Down Expand Up @@ -138,12 +138,12 @@ jobs:
```

In the above yml content, env and jobs are described to send API documents.<br />
The job works as follows, where on a push commit to the github repo the specified `api_files` will be sent to the discovery service repo of the given `provider_org` at location `api_host` using the `api_key` to authenticate with the discovery service.<br />
The job will only send the files to the discovery service in the case where any one of the mentioned file has been updated and changed in the commit,
The job works as follows, where on a push commit to the GitHub repo the specified `api_files` will be sent to the discovery service repo of the given `provider_org` at location `api_host` using the `api_key` to authenticate with the discovery service.<br />
The job will only send the files to the discovery service if any of the mentioned files has been updated and changed in the commit,
or when you first create or update the `discover-api.yml` file.<br />
`API_FILES` can be replaced with `API_FOLDERS` when the entire folder/folders needs to be sent. The content can be modified according to the test requirement for sending the APIs

Please refer [here](https://github.com/ibm-apiconnect/apic-discovery-test) which have a working examples of the test repo to be created like.
Please refer to [here](https://github.com/ibm-apiconnect/apic-discovery-test) which has working examples of the test repo to be created.

## More details on setting up a sample GitHub Action
For more details on how to set up a GitHub Action workflows in your Github repo in general see [the quickstart guide](https://docs.github.com/en/actions/quickstart).
For more details on how to set up a GitHub Action workflow in your GitHub repo in general see [the quickstart guide](https://docs.github.com/en/actions/quickstart).

0 comments on commit ae33e2b

Please sign in to comment.