API styleguide

With API styleguides, you can ensure all APIs in your Redocly Workflows organization are consistent and compliant with your API design principles.

In the context of Redocly tools, an API styleguide is a custom configuration that defines rules for validating your API definitions.

The advantage of using API styleguides in Redocly Workflows is that you can quickly apply the same rules across all your APIs in the registry, instead of having to manually modify separate configuration files for each API.

Additionally, you can enforce API governance by making it required for API registry builds to pass API styleguide validation.

Organization owners can manage their organization's styleguide from the API styleguide page.

API styleguide

Create a new styleguide

  1. Log into Workflows, and navigate to the Settings > API styleguide page.
  2. The Configuration section on the page is a code editor. Add your styleguide into the code editor. The styleguide must be structured like the lint object of the Redocly configuration file . The only allowed configuration objects are lint , extends and rules , like in the following example:
Copy
Copied
lint:
  extends:
   - recommended
  rules:
   no-ambiguous-paths: error
   paths-kebab-case: error

Any other properties will cause validation errors.

Incorrect styleguide exampleCorrect styleguide example
Copy
Copied
apis:
  main:
    root: ./petstore.yaml
lint:
  plugins:
    ./custom-plugin.js
  rules:
    tag-description: off
    no-server-trailing-slash: error
    operation-summary: error
Copy
Copied
lint:
  extends:
    - recommended
  rules:
    tag-description: off
    no-server-trailing-slash: error
    operation-summary: error
  1. Optionally, select the Require API styleguide validation checkbox to prevent API registry builds for APIs that don't conform to your style guide.
  2. Select Save to finish creating the style guide.

Modify an existing styleguide

  1. Log into Workflows, and navigate to the Settings > API styleguide page.
  2. The Configuration section should contain an existing styleguide. To remove its contents altogether, select Clear at the bottom of the page.
  3. To modify parts of the styleguide, make changes to it in the Configuration section.
  4. Select Save to apply your changes.

Integrate API styleguide in the registry

Every build page in the API registry contains information about the API styleguide validation status.

To access the build page, select an API version in the registry. On the Overview page, go to Logs and select a build. API styleguide should be visible as one of the build process steps.

By default, if you don't have any API styleguide configuration, the API styleguide step is skipped in the build.

API styleguide no config

When your API definition is valid, the API styleguide step indicates a pass, and the build is successful.

API styleguide valid

When Require API styleguide validation is selected in the API styleguide configuration, the build will fail if your API definition doesn't conform to the styleguide.

API styleguide not valid

In this case, validation errors caused by the API styleguide will be attached to the Results section. You can distinguish them from other errors by the prefix API styleguide: that indicates their source.