Add Script for Creating Swagger APIViews

eng/pipelines/swagger-apiview.yml

@@ -1,3 +1,11 @@
+parameters:
+  - name: AzureSdkForNetDevOpsFeed
+    type: string
+    default: 'https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-net/nuget/v3/index.json'
+  - name: SwaggerApiParserVersion
+    type: string
+    default: '1.0.0-dev.20240828.2'
+
 trigger: none
 
 jobs:
@@ -8,6 +16,22 @@ jobs:
 
   steps:
   - pwsh: |
-      $(Build.SourcesDirectory)/eng/scripts/Swagger-APIView.ps1 -Verbose
-    displayName: Swagger APIView Check
+      dotnet tool install Azure.Sdk.Tools.SwaggerApiParser `
+        --version ${{ parameters.SwaggerApiParserVersion }}  `
+        --add-source ${{ parameters.AzureSdkForNetDevOpsFeed }} `
+        --global
+    displayName: Install APIView Swagger Parser
+
+  - pwsh: |
+      $(Build.SourcesDirectory)/eng/scripts/Swagger-APIView.ps1 `
+        -TempDirectory $(Agent.TempDirectory) `
+        -ArtiFactsDirectory $(Build.ArtifactStagingDirectory) `
+        -SourceCommitId $(System.PullRequest.SourceBranch) `
+        -TargetCommitId $(System.PullRequest.TargetBranch)
+    displayName: Generate Swagger APIView Tokens
+    ignoreLASTEXITCODE: true
+
+  - pwsh: |
+      Get-ChildItem -Path $(Build.ArtifactStagingDirectory) -Recurse
+    displayName: See Generated Files
     ignoreLASTEXITCODE: true

eng/scripts/Swagger-APIView.ps1

@@ -1,9 +1,170 @@
+param (
+    [Parameter(Mandatory = $true)]
+    [string]$TempDirectory,
+    [Parameter(Mandatory = $true)]
+    [string]$ArtiFactsDirectory,
+    [Parameter(Mandatory = $true)]
+    [string]$SourceCommitId,
+    [Parameter(Mandatory = $true)]
+    [string]$TargetCommitId
+)
+
 . "$PSScriptRoot/ChangedFiles-Functions.ps1"
 
+# ANSI Color Codes
+$esc = [char]27
+$red = "${esc}[31m"
+$green = "${esc}[32m"
+$reset = "${esc}[0m"
+
+<#
+.DESCRIPTION
+  Get the readme.md file associated with a swagger file.
+
+.PARAMETER SwaggerFile
+  Path to a swagger files inside the 'specification' directory.
+
+.OUTPUTS
+  the readme.md file associated with the swagger file or null if not found.
+#>
+function Get-SwaggerReadMeFile {
+    param (
+        [Parameter(Mandatory = $true)]
+        [string]$SwaggerFile
+    )
+
+    $currentPath = Resolve-Path $SwaggerFile
+
+    while ($currentPath -ne [System.IO.Path]::GetPathRoot($currentPath)) {
+        $currentPath = [System.IO.Path]::GetDirectoryName($currentPath)
+        $readmeFile = Get-ChildItem -Path $currentPath -Filter "readme.md" -File -ErrorAction SilentlyContinue
+        if ($readmeFile -and $readmeFile.Name -eq "readme.md") {
+            return $readmeFile.FullName
+        }
+    }
+
+    return $null
+}
+
+<#
+.DESCRIPTION
+  Use the directory structure convention to get the resource provider name.
+
+.PARAMETER ReadMeFilePath
+  ReadMe File Path for a resource provider.
+
+.OUTPUTS
+  The resource provider name.
+#>
+function Get-ResourceProviderFromReadMePath {
+    param (
+        [Parameter(Mandatory = $true)]
+        [string]$ReadMeFilePath
+    )
+
+    $directoryPath = [System.IO.Path]::GetDirectoryName($ReadMeFilePath)
+    $resourceProviderDirectory = Get-ChildItem -Path $directoryPath -Directory | Select-Object -First 1
+    return $resourceProviderDirectory.Name
+}
+
+<#
+.DESCRIPTION
+  Invoke the swagger parset to generate APIView tokens.
+
+.PARAMETER Type
+  New or Baseline swagger APIView tokens.
+
+.PARAMETER ReadMeFilePath
+  The Swagger ReadMeFilePath.
+
+.PARAMETER ResourceProvider
+  The ResourceProvider Name.
+
+.PARAMETER Tag
+  The Tag to use for generating the APIView Tokens.
+
+.PARAMETER TokenDirectory
+  The directory to store the generated APIView Tokens.
+
+.OUTPUTS
+  The resource provider name.
+#>
+function Invoke-SwaggerAPIViewParser {
+    param (
+        [ValidateSet("New", "Baseline")]
+        [Parameter(Mandatory = $true)]
+        [string]$Type,
+        [Parameter(Mandatory = $true)]
+        [string]$ReadMeFilePath,
+        [Parameter(Mandatory = $true)]
+        [string]$ResourceProvider,
+        [Parameter(Mandatory = $true)]
+        [string]$TokenDirectory,
+        [string]$Tag
+    )
+    $tempWorkingDirectoryName = [guid]::NewGuid().ToString()
+    $tempWorkingDirectoryPath = [System.IO.Path]::Combine($TempDirectory, $tempWorkingDirectoryName)
+    New-Item -ItemType Directory -Path $tempWorkingDirectoryPath
+
+    Set-Location -Path $tempWorkingDirectoryPath
+
+    try {
+      # Generate Swagger APIView tokens
+      $command = "& dotnet swaggerAPIParser --readme $readMeFile --package-name $resourceProvider --use-tag-for-output"
+
+      if ($Tag) {
+          $command += " --tag $Tag"
+      }
+
+      Invoke-Expression $command
+      $generatedAPIViewTokenFile = Get-ChildItem -Path $tempWorkingDirectoryPath -File | Select-Object -First 1
+      $readMeTag = $generatedAPIViewTokenFile.BaseName
+
+      Write-Host "${green}Generated '$Type' APIView Token File using file, '$readMeFile' and tag '$readMeTag'${reset}"
+
+      $apiViewTokensFilePath = [System.IO.Path]::Combine($TokenDirectory, "$resourceProvider.$Type.json")
+      Move-Item -Path $generatedAPIViewTokenFile.FullName -Destination $apiViewTokensFilePath -Force
+      return $readMeTag
+    } catch {
+      Write-Host "${red}Failed to generate '$Type' APIView Tokens using '$readMeFile' for '$resourceProvider'${reset}"
+      throw
+    } finally {
+      if (Test-Path -Path $tempWorkingDirectoryPath) {
+        Remove-Item -Path $tempWorkingDirectoryPath -Recurse -Force
+      }
+    }
+}
+
 # Get Changed Swagger Files
-$changedFiles = Get-ChangedFiles -baseCommitish "d69e0e4005427ac68c21618afe1e856790b956b3" -targetCommitish "e6094e6653921fca7b0b61fbc3e6e7c351e58093"
+$changedFiles = Get-ChangedFiles -baseCommitish $BaseCommitId -targetCommitish $TargetCommitId
 $changedSwaggerFiles = Get-ChangedSwaggerFiles -changedFiles $changedFiles
 
-$changedSwaggerFiles | ForEach-Object { Write-Output $_ }
+# Get Related Swagger ReadMe Files
+$swaggerReadMeFiles = [System.Collections.Generic.HashSet[string]]::new()
+$changedSwaggerFiles | ForEach-Object {
+    $readmeFile = Get-SwaggerReadMeFile -swaggerFile $_
+    if ($readmeFile) {
+        $swaggerReadMeFiles.Add($readmeFile) | Out-Null
+    }
+}
+
+$currentBranch = git rev-parse --abbrev-ref HEAD
+
+# Generate Swagger APIView Tokens
+foreach ($readMeFile in $swaggerReadMeFiles) {
+    $resourceProvider = Get-ResourceProviderFromReadMePath -ReadMeFilePath $readMeFile
+    $tokenDirectory = [System.IO.Path]::Combine($ArtiFactsDirectory, $resourceProvider)
+    New-Item -ItemType Directory -Path $tokenDirectory
+
+    Write-Host "${$blue}Generating APIView Tokens using '$readMeFile' for '$resourceProvider'${reset}"
+
+    # Generate New APIView Token using default tag on base branch
+    git checkout $BaseCommitId
+    $defaultTag = Invoke-SwaggerAPIViewParser -Type "New" -ReadMeFilePath $readMeFile -ResourceProvider $resourceProvider -TokenDirectory $tokenDirectory
+
+    # Generate BaseLine APIView Token using same tag on target branch
+    get chekout $TargetCommitId
+    Invoke-SwaggerAPIViewParser -Type "Baseline" -ReadMeFilePath $readMeFile -ResourceProvider $resourceProvider -TokenDirectory $tokenDirectory -Tag $defaultTag | Out-Null
+}
 
-# Get Tags from Changed Swagger files
+git checkout $currentBranch