Azure / Azure/azure-rest-api-specs

[Swagger APIView] Fails if spec does not contain header "### Basic Information"

Open
#33,147 0 comments 0 reactions 1 assignee Claimed by @chidozieononiwu View on GitHub
Central-EngSys
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.