https://github.com/gravitee-io/gravitee-apim-api-docs
https://github.com/gravitee-io/gravitee-apim-api-docs
security-scan
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/gravitee-io/gravitee-apim-api-docs
- Owner: gravitee-io
- Created: 2026-05-04T14:35:54.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-19T18:08:25.000Z (about 2 months ago)
- Last Synced: 2026-05-28T07:40:37.790Z (about 1 month ago)
- Topics: security-scan
- Language: JavaScript
- Size: 1.79 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# gravitee-apim-api-docs
Static site aggregating Gravitee APIM REST API documentation across versions, rendered with [Stoplight Elements](https://stoplight.io/open-source/elements). Published via **GitHub Pages** from the `gh-pages` branch.
## Branch layout
| Branch | Contains | Role |
|---|---|---|
| `main` | `index.html`, `assets/`, `scripts/ingest.sh`, `.circleci/`, this README | Source of truth — code reviewed here. |
| `gh-pages` | `index.html`, `assets/`, `specs/versions.json`, `specs//...` | Deployable artifact served by GitHub Pages. Rebuilt automatically by the ingest CI job; do not edit by hand. |
`specs/` is intentionally absent from `main`. To preview the site locally with real data, run the ingest script (see below) or check out `gh-pages`.
## Local preview
Populate `specs/` first, then serve:
```bash
./scripts/ingest.sh 4.11.5
python3 -m http.server 8080
# open http://localhost:8080
```
## Ingest a new version
```bash
./scripts/ingest.sh
# example:
./scripts/ingest.sh 4.11.5
```
The script downloads the four APIM REST API jars from Maven (Gravitee Nexus / Maven Central), extracts the embedded OpenAPI yaml files into `specs//`, and updates `specs/versions.json`. No APIM source checkout or local Maven build is required.
## APIs included
- Automation (`open-api.yaml`)
- Portal (`portal-openapi.yaml`)
- Management v1 (`console-openapi.yaml`, generated at APIM build time)
- Management v2 — one entry per domain (`openapi-apis.yaml`, `openapi-plugins.yaml`, …)
## Automated deployment (CircleCI)
Two workflows in `.circleci/config.yml`:
1. **`ingest`** — triggered by an external API call (typically from APIM's release pipeline) with a `version` parameter. Runs the ingest script, syncs the result onto `gh-pages`, and commits as `gravitee-bot`. Can also be triggered manually from the CircleCI UI. The job first polls Maven Central for up to one hour to wait for Sonatype's release to propagate; this absorbs the typical 10–30 min sync delay between an APIM release and the artifact becoming downloadable.
2. **`deploy-static`** — triggered on every push to `main`. Syncs `index.html` and `assets/` onto `gh-pages` without touching `specs/`, so UI changes ship immediately.
### Triggering an ingestion manually
From the CircleCI UI: open the docs project, "Trigger Pipeline", set parameter `version` to the target APIM version (e.g. `4.11.5`), run.
Equivalent API call:
```bash
curl -X POST \
https://circleci.com/api/v2/project/gh/gravitee-io/gravitee-apim-api-docs/pipeline \
-H "Circle-Token: $CIRCLE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"parameters":{"version":"4.11.5"}}'
```