search

Azure / azure-sdk-tools

Tools repository leveraged by the Azure SDK team.
MIT License
110 stars 173 forks source link

Migrate REST API docs previews to use reference.config.yml #8468

Open danieljurek opened 3 months ago

danieljurek commented 3 months ago

Production system currently uses reference.config.yml, but automation generates a mapping.json... the mapping.json system is deprecated.

Example error that might be coming from mapping.json generation: https://github.com/Azure/azure-rest-api-specs-pr/pull/17939/checks?check_run_id=26243917599

Update: As @nickwalkmsft pointed out below, this is not the cause of the failure linked above. The reason for that particular failure was because of the additions of two new workflow files, sdk-suppressions.yaml and suppressions.yaml, being added but not excluded from the function that determines which changed files in a PR are swagger files. This issue was fixed in the openapi-apls repository by @mikeharder in this PR.

Right now, the automation will handle both reference.config.yml and mapping.json and we should still ultimately move the REST API docs previews to use the reference.config.yaml.

nickwalkmsft commented 2 months ago

Hi - I'm the PM lead from the Learn ref docs generation team. I wanted to provide a bit of context on this for anyone who sees it.

First and foremost: for authors of PRs in azure-rest-api-specs, the workflow to get help with Swagger ApiDocPreview docs build failures is to file a SiteHelp ticket, see here.

On mapping.json vs. reference.config.yml:

The REST ref docs build is driven by a config file that sits in the docs publishing repo. That file used to be mapping.json. In Oct/Nov the build process was reworked and is now driven by a file called reference.config.yml. We use those config file names to refer to the legacy and new versions of the build process because it's the most externally-visible differentiator.

ApiDocPreview works by pushing config file changes to the AzureRestPreview repo. That config results in a preview build of the OpenAPI specs modified in the PR. It's been doing that with mapping.json this whole time, which works because that codepath in the docs build still exists even though it's been deprecated. When we moved over to the new reference.config.yml system, no corresponding updates to ApiDocPreview were made.

This should be fixed at some point, but I don't believe the use of the legacy config system is the cause of emergent build/verification problems on individual PRs.

JimSuplizio commented 1 month ago

I'm assigning this back to Daniel due to the lack of information and permissions. I'm unable to clone openapi-alps and it would have been good to have linked the PR that migrated to reference.config.yaml from mapping.json in whatever repository it was made in.