Add documentation snippets (#3592)

- Use mdsnippets to get code snippets in markdown from compile-validated code.
- Use badges for dependency versions in README.
- Add dependency of Microsoft.OpenApi to the README.
- Put OpenAPI first (and in bold to indicate the default), and 2.0 for Swagger second.

Author: martincostello

.config/dotnet-tools.json

@@ -7,6 +7,12 @@
       "commands": [
         "dotnet-validate"
       ]
+    },
+    "markdownsnippets.tool": {
+      "version": "27.0.2",
+      "commands": [
+        "mdsnippets"
+      ]
     }
   }
 }

.github/workflows/update-documentation.yml

@@ -0,0 +1,96 @@
+name: update-documentation
+
+on:
+  push:
+    branches: [ master ]
+    paths: [ '**/*.md', 'test/WebSites/DocumentationSnippets/**' ]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  update-docs:
+    name: update-docs
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
+
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+
+      - name: Checkout code
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          filter: 'tree:0'
+          persist-credentials: true # zizmor: ignore[artipacked] Needed to push commits
+          show-progress: false
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@d4c94342e560b34958eacfc5d055d21461ed1c5d # v5.0.0
+
+      - name: Update documentation
+        id: update-docs
+        shell: pwsh
+        env:
+          DOTNET_CLI_TELEMETRY_OPTOUT: true
+          DOTNET_SKIP_FIRST_TIME_EXPERIENCE: true
+          GIT_COMMIT_USER_EMAIL: '41898282+github-actions[bot]@users.noreply.github.com'
+          GIT_COMMIT_USER_NAME: 'github-actions[bot]'
+        run: |
+          $ErrorActionPreference = "Stop"
+          $ProgressPreference = "SilentlyContinue"
+
+          dotnet tool restore
+          dotnet mdsnippets
+
+          $GitStatus = (git status --porcelain)
+          if ([string]::IsNullOrEmpty($GitStatus)) {
+            Write-Output "No changes to commit."
+            exit 0
+          }
+
+          $BranchName = "docs/update-docs"
+          "branchName=$BranchName" >> ${env:GITHUB_OUTPUT}
+
+          git config user.email ${env:GIT_COMMIT_USER_EMAIL} | Out-Null
+          git config user.name ${env:GIT_COMMIT_USER_NAME} | Out-Null
+          git remote set-url "${env:GITHUB_SERVER_URL}/${env:GITHUB_REPOSITORY}.git" | Out-Null
+          git fetch origin | Out-Null
+          git rev-parse --verify --quiet ("remotes/origin/" + $BranchName) | Out-Null
+
+          if ($LASTEXITCODE -eq 0) {
+            Write-Output "Branch $BranchName already exists."
+            exit 0
+          }
+
+          git checkout -b $BranchName
+          git add .
+          git commit -m "Update the code-snippets in the documentation" -s
+          git push -u origin $BranchName
+          "updated-docs=true" >> ${env:GITHUB_OUTPUT}
+
+      - name: Create pull request
+        if: steps.update-docs.outputs.updated-docs == 'true'
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          BASE_BRANCH_NAME: ${{ github.event.repository.default_branch }}
+          HEAD_BRANCH_NAME: ${{ steps.update-docs.outputs.branchName }}
+        with:
+          script: |
+            const { repo, owner } = context.repo;
+            const workflowUrl = `${process.env.GITHUB_SERVER_URL}/${owner}/${repo}/actions/runs/${process.env.GITHUB_RUN_ID}`;
+            const { data: pr } = await github.rest.pulls.create({
+              title: 'Update the code-snippets in the documentation',
+              owner,
+              repo,
+              head: process.env.HEAD_BRANCH_NAME,
+              base: process.env.BASE_BRANCH_NAME,
+              body: [
+                'This PR updates the code-snippets in the documentation.',
+                '',
+                `This pull request was generated by [GitHub Actions](${workflowUrl}).`
+              ].join('\n')
+            });
+            core.notice(`Created pull request ${owner}/${repo}#${pr.number}: ${pr.html_url}`);

README.md

@@ -65,6 +65,7 @@
     <Project Path="test/WebSites/CustomDocumentSerializer/CustomDocumentSerializer.csproj" />
     <Project Path="test/WebSites/CustomUIConfig/CustomUIConfig.csproj" />
     <Project Path="test/WebSites/CustomUIIndex/CustomUIIndex.csproj" />
+    <Project Path="test/WebSites/DocumentationSnippets/DocumentationSnippets.csproj" />
     <Project Path="test/WebSites/GenericControllers/GenericControllers.csproj" />
     <Project Path="test/WebSites/MinimalApp/MinimalApp.csproj" />
     <Project Path="test/WebSites/MinimalAppWithHostedServices/MinimalAppWithHostedServices.csproj" />