Front-end repo for the API documentation site This project is split into 6 internal packages used to build the api-catalog page found at https://developers.redhat.com/api-catalog/
The main package is found on src and contains the Next.js application.
Other packages includes:
- Common code shared across other packages. Contains the information about the included APIs.
- Discovery contains a file descriptor and its supporting schemas to describe the contents found in API catalog. It includes the list of the APIs, what group they form part of and their metadata.
- Sitemap is a cli tool to create the sitemap.xml of API catalog. The sitemap package is also responsible for generating the canonical format json file used by the Search Platform for indexing.
- transform is a cli tool to process the discovery file and create typescript code that can be loaded by API Catalog, the resulting code is stored in the Common code package.
New APIs can be added on the discovery file. The file follows a json schema.
The top element of this file is the apis property. This contains groups of applications.
This group is only used for organizing the applications, and has no impact on the way the applications are displayed.
The other top element is tags and contains the possible tags, each tag has a display name, a type and
the developer.redhat.com taxonomy metadata if any.
For more information head over to the json schema.
| Note: CI makes use of this file to generate the API content |
|---|
To add a new application to an existing group (i.e. hcc-insights) one must append to the api[].apps array e.g.
apis:
- id: hcc-insights
name: Hybrid Cloud Console and Insights
apps:
- id: my-new-app # application's id
name: My New Application # The display name of the application
description: This is my new application # A description for the application
url: https://.... # An URL pointing to the API
apiType: openapi-v3 # Format of the API content
icon: insights # One of the available icons
tags: # List of tags
- rhel
- insightsTo add a new group, just add an entry to apis array e.g.
apis:
- id: my new group
name: This is my new group name
apps:
- id: at-least-one-app
# ...When an application has been decommissioned, you need to remove its entry from the discovery file and then run the discovery process to update the generated files:
npm run discoveryThis will regenerate the API catalog content without the removed application.
This project uses npm and react, the regular steps apply here.
Use npm install to install all the project dependencies.
Use npm run dev to start the frontend application.
Use npm run discovery to star the discovery and transformation process. By default this will build and run the process.
You can specify if you want to run the process without fetching any API by using:
npm run discovery:build && npm run discovery:start -- --skip-api-fetchThe sitemap can be re-generated by running: SITEMAP_BASE_URL=https://my-base-url npm run sitemap.
Details from each API is extracted from its openapi file to show in the API catalog. Sometimes this is not enough. We provide an option to add additional sections. Each section is specified as a markdown file and has a specific place on the API catalog.
The content is rendered in the API catalog using the same look and feel. Here is an example of a getting started section:
A markdown file needs to be added to ./packages/discovery/resources/content under the group-id and api-id using one of the supported sections filenames.
e.g. to add Getting started section for Notifications we need to create the following file: ./packages/discovery/resources/content/hcc-insights/notifications/getting-started.md
This file will be used when regenerating the API files to add a new section on the API catalog.
This is a list of the support sections, followed by the required file name.
- Getting started:
getting-started.md
A GitHub Actions workflow (sync-discovery) keeps API specs up to date. It runs nightly (midnight UTC) and can be triggered manually via workflow_dispatch. It runs npm run discovery to fetch the latest OpenAPI specs from upstream sources, and if any specs have changed, it creates a PR and auto-merges it into main. Once merged, this triggers a new deployment automatically (see Deployment).
Deployments are handled automatically through Konflux, GitLab CI, and SPAship:
- Merging to
maintriggers a Konflux pipeline that builds a container image and pushes it to Quay. - A GitLab CI pipeline (.gitlab-ci.yml) waits for the Quay image, then uses the SPAship CLI to deploy it sequentially to Stage, QA, Dev, and Prod.
Deployment status can be monitored in the SPAship portal.
We require some components that are shared across developers.redhat.com (header and footer). These components needs to be copied (and synchronized from time to time). To do so, we require the sync service provided by SPAship.
If we need to update (or recreate) this configuration we can head over the SPAship portal and go to Settings -> Environment -> Update Sync to configure the environment.
Update the configuration and save by clicking "Sync".
We list the current configuration used on each environment.
{
"autosync": {
"enabled": true,
"targets": [
{
"name": "developers-prod-header",
"interval": "1800s",
"source": {
"url": "https://developers.redhat.com/api/chrome/rh-universal-nav-header"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-universal-nav-header",
"filename": "rh-universal-nav-header.html"
}
},
{
"name": "developers-prod-footer",
"interval": "1800s",
"source": {
"url": "https://developers.redhat.com/api/chrome/rh-unified-footer"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-unified-footer",
"filename": "rh-unified-footer.html"
}
}
]
}
}{
"autosync": {
"enabled": true,
"targets": [
{
"name": "developers-stage-header",
"interval": "3600s",
"source": {
"url": "https://developers.stage.redhat.com/api/chrome/rh-universal-nav-header"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-universal-nav-header",
"filename": "rh-universal-nav-header.html"
}
},
{
"name": "developers-stage-footer",
"interval": "3600s",
"source": {
"url": "https://developers.stage.redhat.com/api/chrome/rh-unified-footer"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-unified-footer",
"filename": "rh-unified-footer.html"
}
}
]
}
}{
"autosync": {
"enabled": true,
"targets": [
{
"name": "developers-qa-header",
"interval": "3600s",
"source": {
"url": "https://developers.qa.redhat.com/api/chrome/rh-universal-nav-header?f=type%7Eapi_catalog"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-universal-nav-header",
"filename": "rh-universal-nav-header.html"
}
},
{
"name": "developers-qa-footer",
"interval": "3600s",
"source": {
"url": "https://developers.qa.redhat.com/api/chrome/rh-unified-footer"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-unified-footer",
"filename": "rh-unified-footer.html"
}
}
]
}
}{
"autosync": {
"enabled": true,
"targets": [{
"name": "developers-dev-header",
"interval": "3600s",
"source": {
"url": "https://developers.dev.redhat.com/api/chrome/rh-universal-nav-header?f=type%7Eapi_catalog"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-universal-nav-header",
"filename": "rh-universal-nav-header.html"
}
},
{
"name": "developers-dev-footer",
"interval": "3600s",
"source": {
"url": "https://developers.dev.redhat.com/api/chrome/rh-unified-footer"
},
"dest": {
"path": "/var/www/html/.include/chrome/rh-unified-footer",
"filename": "rh-unified-footer.html"
}
}]
}
}