- All SDKs are autogenerated using OpenAPI Generator project.
- Bot accounts creates PR with the new versions of the SDK that needs be reviewed by the team
- Once PR is merged developers are responsible for creating tagged release
You may want to generate an SDK locally. See Codegen README for more details
Follow these steps if you wish to add an API client to the SDK for your API service.
The current workflow for API client generation is limited to the services which are part of the bf2fc6cc711aee1a0c2a GitHub organization. If you wish to onboard a service which is in a different GitHub organization please open an issue so that we can discuss options.
In order to send a repository_dispatch
event to the SDK repositories, you need to use a public_repo
scoped personal access token. This token has already been created - ask your organization administrator to add this as a repository secret called APP_SERVICES_CI_TOKEN
.
When a change to the OpenAPI document is merged to the main branch, an event will be sent to each of the SDK repositories, where an API client will be generated using the latest OpenAPI specification document.
Please use the following template to create a GitHub Action in .github/workflows
of your service's repository.
name: Dispatch OpenAPI File Change event
on:
push:
branches:
- main # use whatever your primary Git branch is called.
paths:
- <path/to/openapi/your-service-name.yaml>
jobs:
dispatch:
if: github.repository == 'bf2fc6cc711aee1a0c2a/<your-service-name>'
env:
strategy:
matrix:
repo: ["redhat-developer/app-services-sdk-go", "redhat-developer/app-services-sdk-js", "redhat-developer/app-services-sdk-java"]
runs-on: ubuntu-latest
steps:
- name: Repository Dispatch
uses: peter-evans/repository-dispatch@v1
with:
token: ${{ secrets.APP_SERVICES_CI_TOKEN }}
repository: ${{ matrix.repo }}
event-type: openapi-spec-change
client-payload: '{ "id": "<unique-service-id>/<v1alpha>", "download_url": "<openai_file_download_url>"}'
on.push.branches
: Replace this with the primary branch of your Git repository.on.push.paths
: Replace this with the relative path to the OpenAPI specification document. This ensures that only changes to this file will trigger the event.jobs.dispatch.if
: Replace<your-service-name>
with the name of the GitHub repository. This condition ensures that changes on forks do not trigger this event.jobs.steps[0].with.client-payload
:- Replace
<unique-service-id>
with a clear, unique identifer for your service. Previous examples includekafka-mgmt
andsrs-mgmt
. - Replace
<v1alpha>
with the major API version of your service. - Replace
<openai_file_download_url>
with the direct URL to the raw OpenAPI document. Example: https://raw.githubusercontent.com/bf2fc6cc711aee1a0c2a/kas-fleet-manager/main/openapi/kas-fleet-manager.yaml
- Replace
The Go SDK relies on additional metadata for each API in order to generate code in a "Go" way. Add your API client config to .config/api-client-metadata.json like so:
"foo-mgmt/v1beta": {
"apiGroup": "foomgmt",
"apiVersion": "v1beta",
"release_level": "beta",
}
The "foo-mgmt/v1beta"
key should match the ID from the received client payload which we defined in step 2. The generated client is output to foomgmt/v1beta/client
.
Every API client should have a custom constructor defined one level above the generated client code in foomgmt/v1beta
.
Copy kafkamgmt/apiv1/api_client.go into the foomgmt/v1beta
folder and fix the imports. If you find that that the config is too restrictive for the requirements, please update the APIConfig in internal/api_config.go and start a discussion on a pull request, or open an issue.
If your SDK requires custom code, define them in your desired structure in foomgmt/v1beta
. Please do not add custom code to foomgmt/v1beta/client
as this could be overwritten.
See Codegen README
Run make lint
to perform a lint check of the Go code.