9747d05ae1
* refactor: take clients out of internal * refactor: move stdio to pkg * Move internal/api to api * refactor: final changes for Kapacitor to access shared functionality * chore: regenerate mocks * fix: bad automated refactor * chore: extra formatting not caught by make fmt
54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
# API Contract
|
|
|
|
This directory contains the source YMLs used to drive code generation of HTTP clients in [`api`](../).
|
|
|
|
## YML Structure
|
|
|
|
Most YMLs used here are pulled from the source-of-truth [`openapi`](https://github.com/influxdata/openapi) repo via a git
|
|
submodule. In rare cases, the full description of an API is too complex for our codegen tooling to handle;
|
|
the [`overrides/`](./overrides) directory contains alternate definitions for paths/schemas that work around these cases.
|
|
[`cli.yml`](./cli.yml) ties together all the pieces by linking all routes and schemas used by the CLI.
|
|
|
|
## Updating the API contract
|
|
|
|
To extend/modify the API contract used by the CLI, first make sure the `openapi` submodule is cloned and up-to-date:
|
|
```shell
|
|
# Run from the project root.
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
Then create a new branch to track your work:
|
|
```shell
|
|
git checkout <new-branch-name>
|
|
```
|
|
|
|
Next, decide if any modifications are needed in the source-of-truth `openapi` repo. If so, create a branch in the
|
|
submodule to track changes there:
|
|
```shell
|
|
cd api/contract/openapi && git checkout -b <new-branch-name>
|
|
```
|
|
|
|
Edit/add to the files under `api-contract/` to describe the new API contract. Run the following from the project
|
|
root test your changes and see the outputs in Go code:
|
|
```shell
|
|
make openapi
|
|
# Use `git status` to see new/modified files under `api`
|
|
```
|
|
|
|
Once you're happy with the new API contract, submit your changes for review & merge.
|
|
If you added/edited files within `openapi`, you'll first need to:
|
|
1. Push your submodule branch to GitHub
|
|
```shell
|
|
cd api/contract/openapi && git push <your-branch-name>
|
|
```
|
|
2. Create a PR in `openapi`, eventually merge to `master` there
|
|
3. Update your submodule to point at the merge result:
|
|
```shell
|
|
cd api/contract/openapi && git fetch && git checkout master && git pull origin master
|
|
```
|
|
4. Update the submodule reference from the main repo:
|
|
```shell
|
|
git add api/contract/openapi
|
|
git commit
|
|
```
|