RDSC-5669 Publish RDI Cloud API reference

[ZdravkoDonev-redis]

Summary

• Keep redis/docs as a consumer of the public Cloud API file.
• Download the combined file from the existing /v1/cloud-api-docs endpoint.
• Test the downloaded file before a bot opens an update PR.
• Add a semantic summary of operations, schemas, and source changes to the bot PR.
• Remove API composition from the docs workflow. sm-cloud-api now owns that work.

This PR does not add a new public endpoint. It stays in draft until the sm-cloud-api change is merged and deployed. After that deployment, the docs workflow can update the checked-in OpenAPI file from the existing endpoint.

Related PRs

• RDI Core release file: https://github.com/RedisLabs/redis-data-integration/pull/2681
• Cloud RDI build output: https://github.com/redislabsdev/cloud-rdi-service/pull/667
• Cloud API composition and canonical diagram: https://github.com/redislabsdev/sm-cloud-api/pull/2106

Desired flow

flowchart LR
    subgraph CORE["redis-data-integration"]
        CORE_CODE["RDI Core API code"]
        CORE_CI["CI<br/>Generate and test the OpenAPI file"]
        CORE_FILE["Versioned OpenAPI release"]

        CORE_CODE --> CORE_CI
        CORE_CI --> CORE_FILE
    end

    subgraph CLOUD_RDI["cloud-rdi-service"]
        RDI_CODE["Cloud RDI API code"]
        RDI_CI["CI<br/>Generate and test the OpenAPI file"]
        RDI_FILE["OpenAPI build output"]

        RDI_CODE --> RDI_CI
        RDI_CI --> RDI_FILE
    end

    subgraph CLOUD_API["sm-cloud-api"]
        CAPI_CODE["Cloud API code"]
        COMBINE_CI["CI<br/>Download the selected RDI files<br/>Build and test three OpenAPI files"]
        UPDATE_PR["Bot PR<br/>Update selected versions and generated files"]
        REVIEW["Review and merge"]
        DEPLOY["Deploy sm-cloud-api"]

        CAPI_CODE --> COMBINE_CI
        COMBINE_CI --> UPDATE_PR
        UPDATE_PR --> REVIEW
        REVIEW --> DEPLOY

        DEPLOY --> CAPI_DOCS["/v1/cloud-api-docs/capi"]
        DEPLOY --> RDI_DOCS["/v1/cloud-api-docs/rdi"]
        DEPLOY --> ALL_DOCS["/v1/cloud-api-docs<br/>Combined file"]
    end

    CORE_FILE -->|"Notify sm-cloud-api"| COMBINE_CI
    RDI_FILE -->|"Notify sm-cloud-api"| COMBINE_CI

    subgraph DOCS["redis/docs"]
        CORE_DOCS_CI["CI<br/>Open an RDI Core docs PR"]
        CLOUD_DOCS_CI["Daily CI<br/>Download and test the combined file"]
        CLOUD_DOCS_PR["Bot PR<br/>Update the Cloud API file"]
        DOCS_REVIEW["Review and merge"]
        STAGING["Build documentation staging"]
        PUBLISH["Publish the approved docs release"]

        CORE_DOCS_CI --> DOCS_REVIEW
        CLOUD_DOCS_CI --> CLOUD_DOCS_PR
        CLOUD_DOCS_PR --> DOCS_REVIEW
        DOCS_REVIEW --> STAGING
        STAGING --> PUBLISH
    end

    CORE_FILE --> CORE_DOCS_CI
    ALL_DOCS --> CLOUD_DOCS_CI
    PUBLISH --> CUSTOMER["redis.io API references"]

Loading

The canonical copy of this diagram is in sm-cloud-api/diagrams/rdi-public-api-documentation-flow.md.

Validation

• All 11 OpenAPI tool unit tests pass.
• The workflow passes actionlint and YAML parsing.
• The validator checks the API title, paths, references, operation IDs, exact source metadata, and the exact RDI authentication pair.
• Existing bot PR descriptions are updated when the generated API changes again.
• The workflow only opens a PR after the downloaded combined file passes validation.

[github-actions]

Staging links:
https://redis.io/docs/staging/rdsc-5669-rdi-capi-docs/operate/rc/api/
https://redis.io/docs/staging/rdsc-5669-rdi-capi-docs/operate/rc/rdi/create-workspace/
https://redis.io/docs/staging/rdsc-5669-rdi-capi-docs/operate/rc/rdi/view-edit/

[CLAassistant]

All committers have signed the CLA.

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[cmilesb]

I already mentioned it in our Slack DMs, but it doesn't seem like there's an easy way to keep the data/api file updated. Are we just going to replace the file every time the API get changed? We call the Swagger so that we can keep the docs up to date with what's actually deployed.

@paoloredis - Can you look at the updated workflow to make sure there isn't anything broken or weird?

[paoloredis]

What's the reason for merging the RDI API reference into the RC API reference?

[cmilesb]

@paoloredis This is specifically for the Redis Cloud RDI stuff, so it should go in the Redis Cloud API reference.

[paoloredis]

Why is all of this stuff added here and is not part of the rdi json file in the first place?

[ZdravkoDonev-redis]

The goal was that CAPI exposes functionality not just of the cloud database but all applications as well. So for example, the RDI API is accessible under the CAPI Pro subscriptions path, so on one side it makes sense to document the RDI API in the same place.

If you think we should separate the docs reference, we can also discuss that approach.

TBH I don't have a strong opinion.

[paoloredis]

I'm not against merging the two, but this json manipulation is going to be hard to maintain. Why are all these changes needed for something that's published on https://api.redislabs.com/v1/cloud-api-docs/rdi ? Can the file not be published there with these changes already in place?

[ZdravkoDonev-redis]

Let me rethink the approach and I'll get back.