API Doc Preview

How do I onboard my API to publish docs?

Follow instructions at Publish REST API reference docs

How do I troubleshoot docs build problems?

Follow instructions at Troubleshooting REST API documentation

How does it work?

When a user opens a PR to a specs repo, the spec - api-doc-preview pipeline launches, selects and onboards swaggers into the preview repo, then launches a pipeline in the Learn org to generate an API preview. The spec - api-doc-preview pipeline waits for the Learn org's pipeline to complete, then reports the status back to the PR in the form of a commit status.

 sequenceDiagram
    participant User
    participant spec_api_doc_preview as spec - api-doc-preview (Azure SDK Org)
    participant REST_Preview as REST-Preview-AzureRestPreview (Learn's DevOps Org)

    User->>spec_api_doc_preview: Opens a Pull Request
    spec_api_doc_preview->>spec_api_doc_preview: Generates onboarding info for changed files
    spec_api_doc_preview->>REST_Preview: Launches REST-Preview-AzureRestPreview pipeline
    spec_api_doc_preview->>REST_Preview: Waits for completion
    REST_Preview-->>spec_api_doc_preview: Pipeline completes
    spec_api_doc_preview->>User: Interprets results and sets PR status 

Loading