Investigate centralization of tag descriptions for API spec

Problem to solve

As part of the generation of an OAS spec for GitLab API docs, we want to reuse content when possible. Currently, the existing API documentation includes a short sentence or paragraph at the start of each topic. This content can be directly reused in a YAML file and imported into the OAS spec.

Proposal

Extract the introductory content from each API topic and make it available for reuse in the OpenAPI specification. This intro content can populate the description field for tags and potentially path-level descriptions.

The intro text typically provides context about the API and links to related front-end content (eg, "Use this API to Foo. For more information, see bar"). This is a good fit for OpenAPI tag descriptions, which help organize and document groups of related endpoints.

Initially, we should focus on top-level API topics that map cleanly to OpenAPI tags (e.g., Merge Requests, Issues, Projects, Groups).

Examples output

License API

tags:
  - name: license
    description: |
      Use this API to interact with license endpoints. For more information, see [activate GitLab EE with a license file or key](https://docs.gitlab.com/administration/license_file).

      Prerequisites:

      - You must have administrator access to the instance.

Merge requests API

tags:
  - name: ~~merge-requests~~merge_requests
    description: |
      Use the merge requests API to automate any part of the code review process, and connect your code changes to external tools. Use this API to send information about merge requests to non-GitLab systems, including tools you’ve built yourself, in your preferred format. Based on data returned from those systems, use this API to update, approve, merge, or block those merge requests.

      All API calls to non-public information require authentication.

Implementation approach

The intro content currently lives in the markdown topics for each API topic page (/doc/api/*). This content can be extracted and added to a YAML file that the OAS generation tool can reference. The YAML file will map each tag name to its corresponding description text.

We have already started work on standardizing these intros; we can build off this work.

Approach

  • Audit API topic pages to identify intro content
  • Map intro content to corresponding OAS tags
  • Identify ability to use relative links.
  • Create YAML file structure for storing tag descriptions
  • Extract intro content from markdown and add to YAML file
  • Configure OAS generation tool to import tag descriptions from YAML file
  • Validate that descriptions render correctly in OAS tooling
  • Document process for updating tag descriptions

Success criteria

  • Reuse intros for 20 API topics/tags
    • Small batch to start, can increase if this is working.
  • Tag descriptions stored in centralized YAML file
  • OAS generation tool successfully imports and applies tag descriptions
  • OAS spec validates successfully with all descriptions included
Edited by Isaac Durham