Redocly / Redocly/redocly-cli

Generate all build-docs at once from config.yaml

Open
#1,294 7 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

p2 Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Describe the problem to be solved
Based on the configuration you can specify multiple open api specs and run linter on all of them by default.
https://redocly.com/docs/cli/configuration/#example-redocly-configuration-file
However when I run it for build-docs it output just the first api.

Describe the solution you'd like
I would like it to support the same style as it is for lint for build-docs:

redocly build-docs --config=./config.yaml

Basically it should loop across all apis and generate docs for all of them.
It should be noted that output parameter should be added to the config.

Describe alternatives you've considered
First we tryed running specs it in for loop with detecting file names using jq command. But it was very slow since we have 140 yamls and it takes 5 minutes to run them all (creating new redoc process each time).
Second try was to run them in parallel and it was a lot faster.

Additional context

apis:
  account_activity@v1:
    root: ./folder/account_activity.yaml
    output: ./folder/account_activity.yaml
    theme:
      openapi:
        downloadDefinitionUrl: account_activity.yaml
  account@v1:
    root: ./account.yaml
    output: ./account.html
    theme:
      openapi:
        downloadDefinitionUrl: account.yaml
  api_v2@v1:
    root: ./api_v2/api_v2.yaml
    output: ./api_v2/api_v2.html
    theme:
      openapi:
        downloadDefinitionUrl: api_v2.yaml

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the build-docs command and its handling of config.yaml, focusing on the apis entries and their root, output, and theme values. Compare this with how lint processes multiple APIs. Done means one command generates documentation for every configured API using each API's output path, with coverage for the multi-API configuration.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
cli, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.