Merge pull request #848 from bart-degreed/gen-examples

Generate examples in documentation

Author: Bart Koelman

Build.ps1

@@ -1,7 +1,6 @@
 # Gets the version suffix from the repo tag
 # example: v1.0.0-preview1-final => preview1-final
-function Get-Version-Suffix-From-Tag
-{
+function Get-Version-Suffix-From-Tag {
   $tag=$env:APPVEYOR_REPO_TAG_NAME
   $split=$tag -split "-"
   $suffix=$split[1..2]
@@ -32,25 +31,25 @@ CheckLastExitCode
 
 Write-Output "APPVEYOR_REPO_TAG: $env:APPVEYOR_REPO_TAG"
 
-If($env:APPVEYOR_REPO_TAG -eq $true) {
+if ($env:APPVEYOR_REPO_TAG -eq $true) {
     $revision = Get-Version-Suffix-From-Tag
     Write-Output "VERSION-SUFFIX: $revision"
 
-    IF ([string]::IsNullOrWhitespace($revision)){
+    if ([string]::IsNullOrWhitespace($revision)) {
         Write-Output "RUNNING dotnet pack .\src\JsonApiDotNetCore -c Release -o .\artifacts"
                               dotnet pack .\src\JsonApiDotNetCore -c Release -o .\artifacts
         CheckLastExitCode
     }
-    Else {
+    else {
         Write-Output "RUNNING dotnet pack .\src\JsonApiDotNetCore -c Release -o .\artifacts --version-suffix=$revision"
                               dotnet pack .\src\JsonApiDotNetCore -c Release -o .\artifacts --version-suffix=$revision
         CheckLastExitCode
     }
 }
-Else {
+else {
     $packageVersionSuffix="beta1-$revision"
     Write-Output "VERSION-SUFFIX: $packageVersionSuffix"
     Write-Output "RUNNING dotnet pack .\src\JsonApiDotNetCore -c Release -o .\artifacts --version-suffix=$packageVersionSuffix"
                           dotnet pack .\src\JsonApiDotNetCore -c Release -o .\artifacts --version-suffix=$packageVersionSuffix
     CheckLastExitCode
-}
+}

appveyor.yml

@@ -9,20 +9,20 @@ environment:
 
 # REF: https://github.com/docascode/docfx-seed/blob/master/appveyor.yml
 before_build:
-  - ps: |
-        if(-Not $env:APPVEYOR_PULL_REQUEST_TITLE)
-        {
+  - pwsh: |
+        if (-Not $env:APPVEYOR_PULL_REQUEST_TITLE) {
+            # https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
             git checkout $env:APPVEYOR_REPO_BRANCH -q
             choco install docfx -y
         }
 
 after_build:
-  - ps: |
-        CD ./docs
-        if(-Not $env:APPVEYOR_PULL_REQUEST_TITLE)
-        {
+  - pwsh: |
+        if (-Not $env:APPVEYOR_PULL_REQUEST_TITLE) {
+            CD ./docs
+            & ./generate-examples.ps1
             & docfx docfx.json
-            if ($lastexitcode -ne 0){
+            if ($lastexitcode -ne 0) {
               throw [System.Exception] "docfx build failed with exit code $lastexitcode."
             }
             
@@ -61,8 +61,8 @@ services:
   - postgresql96
 
 build_script:
-- ps: dotnet --version
-- ps: .\Build.ps1
+- pwsh: dotnet --version
+- pwsh: .\Build.ps1
 
 test: off
 

docs/api/index.md

@@ -6,4 +6,4 @@ This section documents the package API and is generated from the XML source comm
 
 - [`JsonApiOptions`](JsonApiDotNetCore.Configuration.JsonApiOptions.yml)
 - [`IResourceGraph`](JsonApiDotNetCore.Configuration.IResourceGraph.yml)
-- [`ResourceDefinition<TResource>`](JsonApiDotNetCore.Resources.ResourceDefinition-1.yml)
+- [`JsonApiResourceDefinition<TResource>`](JsonApiDotNetCore.Resources.JsonApiResourceDefinition-1.yml)

docs/generate-examples.ps1

@@ -0,0 +1,37 @@
+#Requires -Version 7.0
+
+# This script generates response documents for ./request-examples
+
+function Kill-WebServer {
+    $tcpConnections = Get-NetTCPConnection -LocalPort 14141 -ErrorAction SilentlyContinue
+    if ($tcpConnections -ne $null) {
+        Write-Output "Stopping web server"
+        Get-Process -Id $tcpConnections.OwningProcess | Stop-Process
+    }
+}
+
+function Start-Webserver {
+    Write-Output "Starting web server"
+    Start-Job -ScriptBlock { dotnet run --project ..\src\Examples\GettingStarted\GettingStarted.csproj } | Out-Null
+}
+
+Kill-WebServer
+Start-Webserver
+
+Remove-Item -Force -Path .\request-examples\*.json
+
+Start-Sleep -Seconds 10
+
+$scriptFiles = Get-ChildItem .\request-examples\*.ps1
+foreach ($scriptFile in $scriptFiles) {
+    $jsonFileName = [System.IO.Path]::GetFileNameWithoutExtension($scriptFile.Name) + "_Response.json"
+
+    Write-Output "Writing file: $jsonFileName"
+    & $scriptFile.FullName > .\request-examples\$jsonFileName
+
+    if ($LastExitCode -ne 0) {
+        throw [System.Exception] "Example request from '$($scriptFile.Name)' failed."
+    }
+}
+
+Kill-WebServer

docs/generate.sh

@@ -0,0 +1 @@
+curl -s -f http://localhost:14141/api/books

docs/request-examples/000-CREATE_Person.sh

@@ -0,0 +1 @@
+curl -s -f http://localhost:14141/api/people/1

docs/request-examples/001-CREATE_Article.sh

@@ -0,0 +1 @@
+curl -s -f http://localhost:14141/api/books?include=author

docs/request-examples/001_GET_Books.ps1

@@ -0,0 +1 @@
+curl -s -f http://localhost:14141/api/books?fields=publishYear

docs/request-examples/002-GET_Articles.sh

@@ -0,0 +1 @@
+curl -s -f "http://localhost:14141/api/people?filter=contains(name,'Shell')"

docs/request-examples/002_GET_Person-by-ID.ps1

@@ -0,0 +1 @@
+curl -s -f http://localhost:14141/api/books?sort=-publishYear

docs/request-examples/003-GET_Article.sh

@@ -0,0 +1 @@
+curl -s -f "http://localhost:14141/api/books?page%5Bsize%5D=1&page%5Bnumber%5D=2"

docs/request-examples/003_GET_Books-including-Author.ps1

@@ -0,0 +1,10 @@
+curl -s -f http://localhost:14141/api/people        `
+    -H "Content-Type: application/vnd.api+json"     `
+    -d '{
+            \"data\": {
+                \"type\": \"people\",
+                \"attributes\": {
+                    \"name\": \"Alice\"
+                }
+            }
+        }'

docs/request-examples/004-GET_Articles_With_Authors.sh

@@ -0,0 +1,19 @@
+curl -s -f http://localhost:14141/api/books         `
+    -H "Content-Type: application/vnd.api+json"     `
+    -d '{
+            \"data\": {
+                \"type\": \"books\",
+                \"attributes\": {
+                    \"title\": \"Valperga\",
+                    \"publishYear\": 1823
+                },
+                \"relationships\": {
+                    \"author\": {
+                        \"data\": {
+                            \"type\": \"people\",
+                            \"id\": \"1\"
+                        }
+                    }
+                }
+            }
+        }'

docs/request-examples/004_GET_Books-PublishYear.ps1

@@ -0,0 +1,12 @@
+curl -s -f http://localhost:14141/api/books/1       `
+    -H "Content-Type: application/vnd.api+json"     `
+    -X PATCH                                        `
+    -d '{
+            \"data\": {
+                \"type\": \"books\",
+                \"id\": "1",
+                \"attributes\": {
+                    \"publishYear\": 1820
+                }
+            }
+        }'

docs/request-examples/005-PATCH_Article.sh

@@ -0,0 +1,2 @@
+curl -s -f http://localhost:14141/api/books/1       `
+    -X DELETE

docs/request-examples/005_GET_People-Filter_Partial.ps1

@@ -2,18 +2,18 @@
 
 To update these requests:
 
-1. Add a bash (.sh) file prefixed by a number that is used to determine the order the scripts are executed. The bash script should execute a request and output the response. Example:
+1. Add a PowerShell (.ps1) script prefixed by a number that is used to determine the order the scripts are executed. The script should execute a request and output the response. Example:
 ```
-curl -vs http://localhost:5001/api/articles
+curl -s http://localhost:14141/api/books
 ```
 
 2. Add the example to `index.md`. Example:
 ```
-## Get Article with Author
+### Get with relationship
 
-[!code-sh[GET Request](004-GET_Articles_With_Authors.sh)]
-[!code-json[GET Response](004-GET_Articles_With_Authors-Response.json)]
+[!code-ps[REQUEST](003_GET_Books-including-Author.ps1)]
+[!code-json[RESPONSE](003_GET_Books-including-Author_Response.json)]
 ```
 
-3. Run `./generate.sh`
+3. Run `./generate-examples.ps1`
 4. Verify the results by running `docfx --serve`