api-documentation-frontend

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/

Project structure

The main package is found on src and contains the React application for the site itself.

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.
• Prerender is a cli tool to pre-render all the API catalog to increase SEO and make it easier to be read by bots.
• 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.

Updating the discovery file

New APIs can be added on the discovery file. The file follows a json schema.

The top element of this file is the api 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

Adding a new API

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
          - insights

Adding a new Group

To add a new group, just add an entry to api array e.g.

apis:
  - id: my new group
    name: This is my new group name
    apps:
      - id: at-least-one-app
        # ...

Running the components

This project uses npm and react, the regular steps apply here.

Build the application

Use npm install to install all the project dependencies.

Running the frontend

Use npm run start to start the frontend application.

Running the discovery process

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-fetch

Building the sitemap

The sitemap can be re-generated by running: SITEMAP_BASE_URL=https://my-base-url npm run sitemap.

Pre-rendering the site

To be more bot-friendly we pre-render the whole site to allow it to be crawled. You can run trigger a local run by building the site npm run build and then running npm run prerender. The results of the pre-rendering are written in build/pre-rendered

Adding external content

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:

Adding a 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.

Supported sections

This is a list of the support sections, followed by the required file name.

• Getting started: getting-started.md

Releasing to Production

We use GitLab tags for deployment to Production. Follow these steps:

1. Ensure code is ready: Merge all changes for the release into main and ensure they are tested.

2. Create a GitLab Release: Go to "Releases" in GitLab, click "Create a new release". Add a tag name using Semantic Versioning (e.g., v1.0.0). Give it a title, and write any notes about this release.

   When naming your release, follow Semantic Versioning rules:

   • Major version (e.g., v1.0.0 to v2.0.0): You made big changes. Old features might not work.
   • Minor version (e.g., v1.0.0 to v1.1.0): You added something new, but the old features still work.
   • Patch version (e.g., v1.0.0 to v1.0.1): You fixed a small bug and didn't change or add anything else.

3. Trigger the deployment: Creating the release generates a tag that triggers the production deployment pipeline. Our .gitlab-ci.yml includes:

   rules:
     - if: $CI_COMMIT_TAG =~ /^v\d+/
       when: always

   This means the deploy_prod job executes when a tag like v1.0.0 is added.

4. Watch the pipeline: Monitor the pipeline in GitLab's CI/CD > Pipelines section. If successful, your code is deployed to production.