Azure / Azure/azure-rest-api-specs
[Swagger APIView] Fails if spec does not contain header "### Basic Information"
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 424
Description
Swagger APIView failed on this commit:
https://github.com/Azure/azure-rest-api-specs/pull/32790/checks?check_run_id=38528677943
Because the readme.md was missing the header `### Basic Information`, added in this commit:
https://github.com/Azure/azure-rest-api-specs/pull/32790/commits/7b9f71c0af63fad077417db4c73717911e752ad3#diff-d04f288f7618300e40e6bfe9f89a3569bddc9e911d2f3d0d5dc9e3a9c396782e
Source:
https://github.com/Azure/azure-rest-api-specs/blob/250861bb6a886b75255edfa0aa5ee2dd0d6e7a11/eng/scripts/Create-APIView.ps1#L596
I think this is a bug in Swagger APIView, because other checks Iike LintDiff and Avocado were able to process the readme.md file without the `### Basic Information` header.
Here's the previous code in Avocado, which does look for the "Basic Information" header, but also has fallback logic I believe is missing from Swagger APIView.
https://github.com/Azure/avocado/blob/8ced07235393d8b3c55b21e820d9b7b115e060de/src/readme.ts#L60-L82
Overall I see two options:
1. Change apiview pwsh code to match behavior of avocado.getDefaultTag()
2. Port avocado.getDefaultTag() to pure JS code (no dependencies) as a helper in the specs repo, and call it from apiview. You could either port all of apiview to JS, or just shell out to node to run a block of JS code.
Teams discussion: https://teams.microsoft.com/l/message/19:3adeba4aa1164f1c889e148b1b3e3ddd@thread.skype/1741289426487?tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&parentMessageId=1741289426487&teamName=Azure%20SDK&channelName=APIView&createdTime=1741289426487
Contributor guide
Assessment
This issue has not been assessed yet.