Autogenerated API docs

.gitignore

@@ -187,6 +187,10 @@ packages.config.md5sum
 **/.idea/**/*.iml
 **/.idea/**/contentModel.xml
 **/.idea/**/modules.xml
+
 # ignore node_modules symlink
 node_modules
 node_modules.nosync
+
+# API doc generation
+.config/

azure-pipelines.yml

@@ -31,6 +31,7 @@ pr:
   paths:
     exclude:
     - src/NzbDrone.Core/Localization/Core
+    - src/Radarr.Api.*/openapi.json
 
 stages:
   - stage: Setup
@@ -849,6 +850,59 @@ stages:
           cliProjectVersion: '$(radarrVersion)'
           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: windows-2019
+
+      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 .
+          if git status | grep -q 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/radarr/radarr/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/Prowlarr.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.2.3 Swashbuckle.AspNetCore.Cli
+
+dotnet tool run swagger tofile --output ./src/Prowlarr.Api.V1/openapi.json "$outputFolder/net6.0/$RUNTIME/radarr.console.dll" v1 &
+
+sleep 10
+
+kill %1
+
+exit 0

src/NzbDrone.Host/Radarr.Host.csproj

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

src/NzbDrone.Host/Startup.cs

@@ -10,6 +10,7 @@ using Microsoft.AspNetCore.Mvc;
 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,73 @@ namespace NzbDrone.Host
             })
             .AddControllersAsServices();
 
+            services.AddSwaggerGen(c =>
+            {
+                c.SwaggerDoc("v3", new OpenApiInfo
+                {
+                    Version = "3.0.0",
+                    Title = "Radarr",
+                    Description = "Radarr API docs",
+                    License = new OpenApiLicense
+                    {
+                        Name = "GPL-3.0",
+                        Url = new Uri("https://github.com/Radarr/Radarr/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, new 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:7878" } }
+                    }
+                });
+
+                c.AddSecurityDefinition("apikey", apikeyQuery);
+
+                c.AddSecurityRequirement(new OpenApiSecurityRequirement
+                {
+                    { apikeyQuery, new string[] { } }
+                });
+            });
+
             services
             .AddSignalR()
             .AddJsonProtocol(options =>
@@ -198,6 +266,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");