Update API Docs

azure-pipelines.yml

@@ -955,6 +955,60 @@ stages:
           cliProjectVersion: '$(readarrVersion)'
           cliSources: './frontend'
       - task: SonarCloudAnalyze@1
+      
+    - job: Api_Docs
+      displayName: API Docs
+      dependsOn: Prepare
+      condition: |
+        and
+        (
+          and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/develop')),
+          and(succeeded(), eq(dependencies.Prepare.outputs['setVar.backendNotUpdated'], '0'))
+        )
+
+      pool:
+        vmImage: ${{ variables.windowsImage }}
+
+      steps:
+      - task: UseDotNet@2
+        displayName: 'Install .net core'
+        inputs:
+          version: $(dotnetVersion)
+      - checkout: self
+        submodules: true
+        persistCredentials: true
+        fetchDepth: 1    
+      - bash: ./docs.sh Windows
+        displayName: Create openapi.json
+      - bash: |
+          git config --global user.email "development@lidarr.audio"
+          git config --global user.name "Servarr"
+          git checkout -b api-docs
+          git add .
+          git status
+          if git status | grep modified
+          then
+            git commit -am 'Automated API Docs update'
+            git push -f --set-upstream origin api-docs
+            curl -X POST -H "Authorization: token ${GITHUBTOKEN}" -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/readarr/readarr/pulls -d '{"head":"api-docs","base":"develop","title":"Update API docs"}'
+          else
+            echo "No changes since last run"
+          fi
+        displayName: Commit API Doc Change
+        continueOnError: true
+        env:
+          GITHUBTOKEN: $(githubToken)
+      - task: CopyFiles@2
+        displayName: 'Copy openapi.json to: $(Build.ArtifactStagingDirectory)'
+        inputs:
+          SourceFolder: '$(Build.SourcesDirectory)'
+          Contents: |
+            **/*openapi.json
+          TargetFolder: '$(Build.ArtifactStagingDirectory)/api_docs'
+      - publish: $(Build.ArtifactStagingDirectory)/api_docs
+        artifact: 'APIDocs'
+        displayName: Publish API Docs Bundle
+        condition: and(succeeded(), eq(variables['System.JobAttempt'], '1'))
 
     - job: Analyze_Backend
       displayName: Backend

docs.sh

@@ -0,0 +1,38 @@
+PLATFORM=$1
+
+if [ "$PLATFORM" = "Windows" ]; then
+  RUNTIME="win-x64"
+elif [ "$PLATFORM" = "Linux" ]; then
+  WHERE="linux-x64"
+elif [ "$PLATFORM" = "Mac" ]; then
+  WHERE="osx-x64"
+else
+  echo "Platform must be provided as first arguement: Windows, Linux or Mac"
+  exit 1
+fi
+
+outputFolder='_output'
+testPackageFolder='_tests'
+
+rm -rf $outputFolder
+rm -rf $testPackageFolder
+
+slnFile=src/Readarr.sln
+
+platform=Posix
+
+dotnet clean $slnFile -c Debug
+dotnet clean $slnFile -c Release
+
+dotnet msbuild -restore $slnFile -p:Configuration=Debug -p:Platform=$platform -p:RuntimeIdentifiers=$RUNTIME -t:PublishAllRids
+
+dotnet new tool-manifest
+dotnet tool install --version 6.3.0 Swashbuckle.AspNetCore.Cli
+
+dotnet tool run swagger tofile --output ./src/Readarr.Api.V1/openapi.json "$outputFolder/net6.0/$RUNTIME/Readarr.console.dll" v1 &
+
+sleep 45
+
+kill %1
+
+exit 0

src/Directory.Packages.props

@@ -45,6 +45,7 @@
     <PackageVersion Include="SharpZipLib" Version="1.3.3" />
     <PackageVersion Include="SixLabors.ImageSharp" Version="2.1.3" />
     <PackageVersion Include="StyleCop.Analyzers" Version="1.1.118" />
+    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerGen" Version="6.3.0" />
     <PackageVersion Include="System.Buffers" Version="4.5.1" />
     <PackageVersion Include="System.Configuration.ConfigurationManager" Version="6.0.0" />
     <PackageVersion Include="System.Data.SQLite.Core.Servarr" Version="1.0.115.5-18" />

src/NzbDrone.Host/Readarr.Host.csproj

@@ -6,6 +6,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" />
     <PackageReference Include="DryIoc.dll" />
+    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" />
     <PackageReference Include="DryIoc.Microsoft.DependencyInjection" />
     <PackageReference Include="System.Text.Encoding.CodePages" />
   </ItemGroup>

src/NzbDrone.Host/Startup.cs

@@ -9,6 +9,7 @@ using Microsoft.AspNetCore.HttpOverrides;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
+using Microsoft.OpenApi.Models;
 using NLog.Extensions.Logging;
 using NzbDrone.Common.EnvironmentInfo;
 using NzbDrone.Common.Instrumentation;
@@ -92,6 +93,78 @@ namespace NzbDrone.Host
             })
             .AddControllersAsServices();
 
+            services.AddSwaggerGen(c =>
+            {
+                c.SwaggerDoc("v1", new OpenApiInfo
+                {
+                    Version = "1.0.0",
+                    Title = "Readarr",
+                    Description = "Readarr API docs",
+                    License = new OpenApiLicense
+                    {
+                        Name = "GPL-3.0",
+                        Url = new Uri("https://github.com/Readarr/Readarr/blob/develop/LICENSE")
+                    }
+                });
+
+                var apiKeyHeader = new OpenApiSecurityScheme
+                {
+                    Name = "X-Api-Key",
+                    Type = SecuritySchemeType.ApiKey,
+                    Scheme = "apiKey",
+                    Description = "Apikey passed as header",
+                    In = ParameterLocation.Header,
+                    Reference = new OpenApiReference
+                    {
+                        Type = ReferenceType.SecurityScheme,
+                        Id = "X-Api-Key"
+                    },
+                };
+
+                c.AddSecurityDefinition("X-Api-Key", apiKeyHeader);
+
+                c.AddSecurityRequirement(new OpenApiSecurityRequirement
+                {
+                    { apiKeyHeader, Array.Empty<string>() }
+                });
+
+                var apikeyQuery = new OpenApiSecurityScheme
+                {
+                    Name = "apikey",
+                    Type = SecuritySchemeType.ApiKey,
+                    Scheme = "apiKey",
+                    Description = "Apikey passed as header",
+                    In = ParameterLocation.Query,
+                    Reference = new OpenApiReference
+                    {
+                        Type = ReferenceType.SecurityScheme,
+                        Id = "apikey"
+                    },
+                };
+
+                c.AddServer(new OpenApiServer
+                {
+                    Url = "{protocol}://{hostpath}",
+                    Variables = new Dictionary<string, OpenApiServerVariable>
+                    {
+                        { "protocol", new OpenApiServerVariable { Default = "http", Enum = new List<string> { "http", "https" } } },
+                        { "hostpath", new OpenApiServerVariable { Default = "localhost:8787" } }
+                    }
+                });
+
+                c.AddSecurityDefinition("apikey", apikeyQuery);
+
+                c.AddSecurityRequirement(new OpenApiSecurityRequirement
+                {
+                    { apikeyQuery, Array.Empty<string>() }
+                });
+            });
+
+            services.ConfigureSwaggerGen(options =>
+            {
+                options.CustomSchemaIds(x => x.FullName);
+            });
+
             services
             .AddSignalR()
             .AddJsonProtocol(options =>
@@ -188,6 +261,15 @@ namespace NzbDrone.Host
 
             app.UseWebSockets();
 
+            // Enable middleware to serve generated Swagger as a JSON endpoint.
+            if (BuildInfo.IsDebug)
+            {
+                app.UseSwagger(c =>
+                {
+                    c.RouteTemplate = "docs/{documentName}/openapi.json";
+                });
+            }
+
             app.UseEndpoints(x =>
             {
                 x.MapHub<MessageHub>("/signalr/messages").RequireAuthorization("SignalR");