From dab0cf48c641fd644f247c1d46a34b27480e838a Mon Sep 17 00:00:00 2001 From: Chaim Lev-Ari Date: Thu, 4 Jun 2026 09:13:45 +0300 Subject: [PATCH] docs(api): document CE type generation [BE-13031] (#2794) Co-authored-by: Claude --- CONTRIBUTING.md | 2 ++ README.md | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e34f82b20..24747dbb0b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -149,6 +149,8 @@ When adding a new route to an existing handler use the following as a template ( explanation about each line can be found (here)[https://github.com/swaggo/swag#api-operation] +After changing these annotations, regenerate the TypeScript API client and types — see [Generating API types](./README.md#generating-api-types). + ## Licensing See the [LICENSE](https://github.com/portainer/portainer/blob/develop/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. diff --git a/README.md b/README.md index accfa31eef..883e4181e4 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,32 @@ You can join the Portainer Community by visiting [https://www.portainer.io/join- - Want to report a bug or request a feature? Please open [an issue](https://github.com/portainer/portainer/issues/new). - Want to help us build **_portainer_**? Follow our [contribution guidelines](https://docs.portainer.io/contribute/contribute) to build it locally and make a pull request. +## Generating API types + +The frontend consumes a TypeScript API client (SDK functions and request/response types) that is generated from the Go API's Swagger annotations. Regenerate it after any API change — a new endpoint, a changed request/response shape, or a removed endpoint: + +```bash +make generate-api +``` + +This runs the following pipeline: + +``` +Go Swagger annotations + → dist/docs/swagger.yaml (make docs-build, via swaggo/swag) + → dist/docs/openapi.yaml (swagger2openapi + validation) + → app/react/portainer/generated-api/portainer/ (hey-api/openapi-ts) +``` + +The generator is configured in [`openapi-ts.config.ts`](./openapi-ts.config.ts), which controls the output path, plugins, and tag filters (for example, `deprecated` endpoints and `edge_agent`-tagged routes are excluded). + +The generated files live in `app/react/portainer/generated-api/portainer/` and must **not** be edited by hand — your changes would be overwritten on the next run. Import the generated SDK functions and types instead of writing direct HTTP calls: + +- `@api/sdk.gen` — SDK functions +- `@api/types.gen` — request/response types + +See [Adding api docs](./CONTRIBUTING.md#adding-api-docs) for how to annotate handlers so they are picked up by the generator. + ## Security For information about reporting security vulnerabilities, please see our [Security Policy](SECURITY.md).