Skip to content
Last updated

Base Queries

Of course! Here are the answers to your questions about using Redocly.

1. How do I protect a page with the "pearl" role?

You can control access to specific pages in your documentation portal using role-based access control (RBAC) defined in your redocly.yaml configuration file. You need to define the roles and then map them to the files you want to protect.

Here's an example of how you can configure your redocly.yaml to only allow users with the "pearl" role to access the debrief.md page:

# redocly.yaml

# 1. Define your access control roles
access:
  roles:
    pearl: # The name of your role
      # You would typically manage role assignment through your identity provider (IdP)
      # This example assumes the role is passed in a JWT claim.
      claim:
        name: 'user_roles' # The name of the claim in the JWT
        value: 'pearl-squad' # The value that grants the "pearl" role

# 2. Define rules for your page
pages:
  - file: docs/debrief.md
    # 3. Apply the role to the page
    access:
      # Only users with the 'pearl' role can view this page.
      # Users without this role will see a 404 Not Found error.
      - pearl

In this configuration:

  • access.roles defines the available roles. Here, we've created a role named pearl.
  • The claim object specifies how to verify the role from a JSON Web Token (JWT). In this case, it checks for a claim named user_roles with the value pearl-squad.
  • Under pages, you specify the file (docs/debrief.md) and then apply the pearl role to it under the access key.

2. How do I create a code walkthrough?

Redocly supports a "code walkthrough" format which is great for explaining code step-by-step. This is achieved by using a special syntax within your Markdown files. You can interleave explanations with code blocks, and Redocly will render them in a side-by-side or stacked view.

To create a code walkthrough, you use --- separators between your Markdown content and the corresponding code blocks.

Here is an example of what the Markdown might look like for a simple Python script:

# Code Walkthrough: Hello World

Here we will walk through a simple "Hello World" in Python.


First, we import the `sys` module, which allows us to interact with the system.

```python
import sys

 Next, we define a simple function called main that takes no arguments.

def main():

 Inside our main function, we print the classic "Hello, World!" string to the standard output. We also include the Python version for fun.

    print("Hello, World!")
    print(f"This is Python version {sys.version}")

 Finally, this standard Python construct checks if the script is being run directly (not imported) and calls the main function if it is.

if __name__ == "__main__":
    main()

When rendered, Redocly will display the descriptive text next to the corresponding code block, making it easy for users to follow along.

### 3. How do I only show the mock server in the Try it console?

You can control which servers are displayed in the "Try it" console by using the `x-redocly-hide-server-vars` extension in your OpenAPI definition. To show *only* the mock server, you can define both your real server and your mock server in the `servers` array, and then use this extension to hide the real one.

Here is an example snippet from an `openapi.yaml` file:

```yaml
# openapi.yaml

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0

# Define your servers
servers:
  # The mock server you want to show
  - url: https://api.redocly.com/mocks/my-api
    description: Mock Server

  # The production server you want to hide from the "Try it" console
  - url: https://api.production.com/v1
    description: Production Server
    x-redocly-hide-server-vars: true # This extension hides the server

paths:
  /users:
    get:
      summary: Get all users
      # ... rest of your path item object

By setting x-redocly-hide-server-vars: true on the production server entry, it will not be selectable in the "Try it" console, effectively leaving only the "Mock Server" as the available option.

4. How do I run API monitoring using Redocly on a regular schedule?

Redocly's API monitoring is typically run as a command within a CI/CD pipeline, which can be configured to execute on a schedule. The primary command for this is redocly test.

Here’s a general process and an example using GitHub Actions to run tests every day at midnight:

Step 1: Configure your tests

First, define your API tests in a file like redocly.yaml or a separate file. These tests can check for things like breaking changes, style guide adherence, and more.

# redocly.yaml

apis:
  main:
    root: openapi/openapi.yaml

# Define assertion rules
assert:
  # This rule checks for breaking changes against the production version of the API
  - subject: api
    ruleId: no-breaking-changes
    against: 'prod' # 'prod' is an alias for the production version

# This command will run the assertions
test:
  apis:
  - main

Step 2: Schedule the test run in your CI/CD

You can use a scheduler like cron or the built-in scheduling features of your CI/CD provider.

Here is an example of a GitHub Actions workflow that runs every day:

# .github/workflows/scheduled-monitoring.yml

name: Scheduled API Monitoring

on:
  schedule:
    # Runs at 00:00 UTC every day
    - cron: '0 0 * * *'

jobs:
  api-monitoring:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Redocly CLI
        uses: redocly/cli-action@v1
        with:
          redocly-api-key: ${{ secrets.REDOCLY_API_KEY }}

      - name: Run Redocly API Tests
        run: redocly test

This workflow will automatically trigger at the specified cron schedule, check out your code, and run the redocly test command.

5. How do I make headings purple colored in Redocly?

You can customize the appearance of your Redocly documentation, including heading colors, through the theme object in your redocly.yaml configuration file.

To change the color of all heading levels (h1 through h6) to purple, you can add a theme.headings.color property.

Here is an example redocly.yaml configuration:

# redocly.yaml

# ... other configurations

theme:
  # You can customize colors, fonts, and more here
  colors:
    primary:
      main: ‘#9d34da’ # Example: A nice shade of purple for primary actions
  
  # Specifically target headings
  headings:
    # You can set font-family, font-weight, etc.
    # To change the color:
    color: ‘#6A0DAD’ # A standard purple hex code

# ... other configurations

In this example:

  • theme.colors.primary.main changes the primary theme color, which affects links, buttons, and other interactive elements.
  • theme.headings.color specifically targets all heading elements and sets their text color to the specified purple hex code (#6A0DAD). You can use any valid CSS color value.