Add Rest Specification Index (#7030)

Initial work to add a rest spec index to our github io site.

_includes/releases/header.md

@@ -27,19 +27,7 @@ Although the older libraries can still be used after deprecation, they will no l
 
 {% endif %}
 
-<small>Last updated: {{ 'now' | date: "%b %Y" }}</small>
+{% include releases/header_search.md  %}
-
-<div class="search-group">
-    <input class="form-control" id="myInput" type="text" placeholder="Search...">
-    <img
-        alt="Copy filter to clipboard"
-        class="search-share search-share-hide"
-        id="searchShare"
-        title="Copy filter link to clipboard"
-        src="{{ "/images/share.png" | relative_url }}"
-        tabindex=0
-        >
-</div>
 
 {% assign header_included = 'true' %}
 {% endif %}

_includes/releases/header_search.md

@@ -0,0 +1,13 @@
+<small>Last updated: {{ 'now' | date: "%b %Y" }}</small>
+
+<div class="search-group">
+    <input class="form-control" id="myInput" type="text" placeholder="Search...">
+    <img
+        alt="Copy filter to clipboard"
+        class="search-share search-share-hide"
+        id="searchShare"
+        title="Copy filter link to clipboard"
+        src="{{ "/images/share.png" | relative_url }}"
+        tabindex=0
+        >
+</div>

_includes/releases/spec_version_summary.md

@@ -0,0 +1,14 @@
+{% if include.versions.size > 0 %}
+{% assign sortedVersions = include.versions | sort: "Version" | reverse %}
+{% assign firstSpec = sortedVersions[0] %}
+<details>
+  <summary>
+    <a href="https://github.com/Azure/azure-rest-api-specs/tree/main/specification/{{ firstSpec.SpecPath }}">{{ firstSpec.Version }}</a>
+  </summary>
+  <ul>  
+  {% for spec in sortedVersions %}
+    <li><a href="https://github.com/Azure/azure-rest-api-specs/blob/main/specification/{{ spec.SpecPath }}">{{ spec.SpecPath }} </a></li>
+  {% endfor %}
+  </ul>
+</details>
+{% endif %}

_includes/releases/specs.md

@@ -0,0 +1,54 @@
+# Azure Rest API Specifications
+
+This page provides an inventory of all Azure Rest API Specifications from [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo. The **Data plane TypeSpec** and **Management TypeSpecs** only show services that have a TypeSpec defined. The **all** table shows all the specs both TypeSpec and OpenAPI. 
+
+{% if include.type == "all" %}
+  {% assign specs = site.data.releases.latest.specs %}
+{% else %}
+  {% assign specs = site.data.releases.latest.specs | where: 'Type', include.type | where: 'IsTypeSpec', 'True' %}
+{% endif %}
+
+{% include releases/header_search.md %}
+
+<ul class="nav nav-tabs">
+  <li class="nav-item {% if include.type == 'data' %}active{% endif %}">
+    <a class="nav-link" href="{{ site.baseurl }}/releases/latest/specs.html">Dataplane TypeSpecs{% if include.type == 'data' %} ({{specs.size}}){% endif %}</a>
+  </li>
+  <li class="nav-item {% if include.type == 'mgmt' %}active{% endif %}">
+    <a class="nav-link" href="{{ site.baseurl }}/releases/latest/mgmt/specs.html">Management TypeSpecs{% if include.type == 'mgmt' %} ({{specs.size}}){% endif %}</a>
+  </li>
+  <li class="nav-item {% if include.type == 'all' %}active{% endif %}">
+    <a class="nav-link" href="{{ site.baseurl }}/releases/latest/all/specs.html">All{% if include.type == 'all' %} ({{specs.size}}){% endif %}</a>
+  </li>
+</ul>
+
+<div class="table-responsive">
+  <table class="table table-bordered table-condensed">
+    <tr>
+      <th scope="col" style="width: 25%;">Service</th>
+      <th scope="col">Stable</th>
+      <th scope="col">Preview</th>
+    </tr>
+    <tbody id="myTable">
+
+    {% assign serviceFamilies = specs | group_by: "ServiceFamily" %}
+    {% for serviceFamily in serviceFamilies %}
+      {% assign resourceNames = serviceFamily.items | group_by: "ResourcePath" %}
+      {% for resourceName in resourceNames %}
+        {% assign typeSpecs = resourceName.items | where: 'IsTypeSpec', 'True' %}
+        <tr scope="row">
+          <td>{{ serviceFamily.name }} - {{ resourceName.name }} {% if typeSpecs.size > 0 %}<small><i>(TypeSpec)</i></small>{%endif%}</td>
+          <td>
+            {% assign stables = resourceName.items | where: 'VersionType', 'stable' %}
+            {% include releases/spec_version_summary.md versions=stables %}
+          </td>
+          <td>
+            {% assign previews = resourceName.items | where: 'VersionType', 'preview' %}
+            {% include releases/spec_version_summary.md versions=previews %}
+          </td>
+        </tr>
+      {% endfor %}
+    {% endfor %}
+    </tbody>
+  </table>
+</div>

eng/scripts/Update-Spec-Versions.ps1

@@ -0,0 +1,126 @@
+[CmdletBinding()]
+param (
+  [string]$specsRoot
+)
+
+Set-StrictMode -Version 3
+$ProgressPreference = "SilentlyContinue"; # Disable invoke-webrequest progress dialog
+
+. (Join-Path $PSScriptRoot PackageList-Helpers.ps1)
+
+# spec - json file
+#  path
+#  name
+#  version
+# TODO: map to SDK library via readme.md or tspconfig.yaml
+
+function CreateSpec($jsonFilesInPath, $relSpecPath)
+{
+  if ($relSpecPath -notmatch "^(?<serviceFamily>[^/]+)/(?<type>data-plane|resource-manager)/(?<rpPath>.+)?(?<verType>preview|stable)/(?<version>[^/]+)$") { 
+    Write-Verbose "Skipping: '$relSpecPath' doesn't match the standard directory path regex"
+    return $null
+  }
+  $serviceFamily = $matches["serviceFamily"]
+  $rpPath = $matches["rpPath"]?.Trim('/')
+  $verType = $matches["verType"]
+  $versionFromPath = $matches["version"]
+  $specType = $matches["type"]
+  if ($specType -eq "data-plane") { $specType = "data" }
+  if ($specType -eq "resource-manager") { $specType = "mgmt" }
+
+  $version = ""
+  $anyTypeSpec = $false
+
+  $jsonFileList = @()
+  $inconsistentVersion = $false
+  foreach ($jsonFile in $jsonFilesInPath) 
+  {
+    $specContent = Get-Content $jsonFile | ConvertFrom-Json -AsHashtable
+    #Write-Host "Processing $jsonFile"
+    
+    if (!$specContent) { Write-Verbose "Failed to read $specPath"; continue }
+    if (!$specContent.ContainsKey("info") -or !$specContent.info.ContainsKey("version")) { Write-Verbose "Skipping: '$jsonFile' doesn't contain info.version"; continue }
+
+    if ($specType -eq "mgmt" -and $specContent.ContainsKey("host") -and $specContent.host -ne "management.azure.com") {
+      Write-Verbose "Found mgmt spec at $specPath without management.azure.com as the host"
+    }
+
+    if (!$version) { $version = $specContent.info.version }
+
+    if ($version -ne $specContent.info.version) {
+      if ($serviceFamily -ne "network") {
+        Write-Verbose "VersionMismatchBetweenOtherSpecs: '$($specContent.info.version)' != '$version' for '$jsonFile'."
+      }
+      $inconsistentVersion = $true
+    }
+
+    # Ignore differences with version starting with v or ending in -preview
+    if (($versionFromPath -replace "v|-preview") -ne ($specContent.info.version -replace "v|-preview")) {
+      if ($serviceFamily -ne "network") {
+        Write-Verbose "VersionMismatchBetweenPathAndSpec: '$versionFromPath' != '$($specContent.info.version)' for '$jsonFile'"
+      }
+    }
+
+    # TODO: Find TypeSpec project
+    if ($specContent.info.ContainsKey('x-typespec-generated')) {
+      $anyTypeSpec = $true
+    }
+
+    $jsonFileList += $jsonFile.Name
+  }
+
+  if ($inconsistentVersion) {
+    $version = "Varies"
+  }
+
+  return [PSCustomObject][ordered]@{
+    SpecPath = $relSpecPath
+    ServiceFamily = $serviceFamily
+    ResourcePath = $rpPath
+    Version = $version
+    VersionType = $verType
+    Type = $specType
+    IsTypeSpec = $anyTypeSpec
+    JsonFiles = ($jsonFileList -join "|")
+  }
+}
+
+function FindAllSpecs($specsRoot)
+{
+  $potentialSpecs = Get-ChildItem -Recurse -Include *.json $specsRoot
+  #TODO: Map to tspconfig if 
+  #$potentialTypeSpecs = Get-ChildItem -Recurse -Include tspconfig.yaml $specsRoot
+
+  $processedPaths = @{}
+  foreach ($potentialSpec in $potentialSpecs)
+  {
+    $specPath = $potentialSpec -replace "\\", "/"
+
+    if ($specPath -match "/(examples|scenarios|restler|common|common-types)/") { continue }
+    if ($specPath -notmatch "specification/(?<relSpecPath>[^/]+/(data-plane|resource-manager).*?/(preview|stable)/([^/]+))/[^/]+\.json$") { continue }
+
+    $relSpecPath = $matches["relSpecPath"]
+
+    if ($processedPaths.ContainsKey($relSpecPath)) { continue }
+
+    $jsonFilesInPath = Get-ChildItem $potentialSpec.Directory *.json
+    $processedPaths[$relSpecPath] = CreateSpec $jsonFilesInPath $relSpecPath
+  }
+  return $processedPaths.Values
+}
+
+function GatherSpecs($specsRoot)
+{
+  $specs = FindAllSpecs $specsRoot | Where-Object { $_ }
+
+  $speclistFile = Join-Path $releaseFolder "specs.csv"
+  Write-Host "Writing $speclistFile"
+
+  $new = @($specs | Where-Object { $_.IsTypeSpec } | Sort-Object ServiceFamily, ResourcePath)
+  $other = @($specs | Where-Object { !$_.IsTypeSpec } |  Sort-Object ServiceFamily, ResourcePath)
+
+  $sortedSpecs = $new + $other
+  $sortedSpecs | ConvertTo-CSV -NoTypeInformation -UseQuotes Always | Out-File $speclistFile -encoding ascii
+}
+
+GatherSpecs $specsRoot

releases/latest/all/specs.md

@@ -0,0 +1,8 @@
+---
+title: Azure Rest API Specs (Latest)
+layout: default
+sidebar: releases_sidebar
+header: true
+---
+{% include releases/specs.md type="all" %}
+{% include refs.md %}

releases/latest/mgmt/specs.md

@@ -0,0 +1,8 @@
+---
+title: Azure Rest API Specs (Latest)
+layout: default
+sidebar: releases_sidebar
+header: true
+---
+{% include releases/specs.md type="mgmt" %}
+{% include refs.md %}

releases/latest/specs.md

@@ -0,0 +1,8 @@
+---
+title: Azure Rest API Specs(Latest)
+layout: default
+sidebar: releases_sidebar
+header: true
+---
+{% include releases/specs.md type="data" %}
+{% include refs.md %}