Autogenerated API docs

.gitignore

@@ -188,6 +188,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

@@ -823,6 +823,50 @@ stages:
           FORCE_COLOR: 0
           YARN_CACHE_FOLDER: $(yarnCacheFolder)
 
+    - 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 # Need history for Sonar analysis
+        submodules: true      
+      - bash: ./docs.sh Windows
+        displayName: Create Openapi.json
+      - bash: git commit -am 'Automated API Docs update'
+        displayName: Commit APIDoc Change  
+      - task: CreatePullRequest@1
+        inputs:
+          repoType: 'GitHub'
+          githubEndpoint: 'github release'
+          githubRepository: '$(Build.Repository.Name)'
+          sourceBranch: 'api-docs'
+          targetBranch: 'develop'
+          title: 'Update API Docs'
+      - 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
       dependsOn: Prepare

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/prowlarr.console.dll" v1 &
+
+sleep 10
+
+kill %1
+
+exit 0

src/NzbDrone.Host/Prowlarr.Host.csproj

@@ -7,6 +7,7 @@
     <PackageReference Include="NLog.Extensions.Logging" Version="1.7.2" />
     <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.1" />
     <PackageReference Include="DryIoc.Microsoft.DependencyInjection" Version="5.1.0" />
   </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;
@@ -90,6 +91,63 @@ namespace NzbDrone.Host
             })
             .AddControllersAsServices();
 
+            services.AddSwaggerGen(c =>
+            {
+                c.SwaggerDoc("v1", new OpenApiInfo
+                {
+                    Version = "1.0.0",
+                    Title = "Prowlarr",
+                    Description = "Prowlarr API docs",
+                    License = new OpenApiLicense
+                    {
+                        Name = "GPL-3.0",
+                        Url = new Uri("https://github.com/Prowlarr/Prowlarr/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.AddSecurityDefinition("apikey", apikeyQuery);
+
+                c.AddSecurityRequirement(new OpenApiSecurityRequirement
+                {
+                    { apikeyQuery, new string[] { } }
+                });
+            });
+
             services
             .AddSignalR()
             .AddJsonProtocol(options =>
@@ -181,6 +239,20 @@ namespace NzbDrone.Host
 
             app.UseWebSockets();
 
+            // Enable middleware to serve generated Swagger as a JSON endpoint.
+            if (BuildInfo.IsDebug)
+            {
+                app.UseSwagger(c =>
+                {
+                    c.PreSerializeFilters.Add((swagger, httpReq) =>
+                    {
+                        swagger.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" } };
+                    });
+
+                    c.RouteTemplate = "docs/{documentName}/openapi.json";
+                });
+            }
+
             app.UseEndpoints(x =>
             {
                 x.MapHub<MessageHub>("/signalr/messages").RequireAuthorization("SignalR");

src/Prowlarr.Api.V1/Profiles/App/AppProfileController.cs

@@ -20,6 +20,7 @@ namespace Prowlarr.Api.V1.Profiles.App
         }
 
         [RestPostById]
+        [Produces("application/json")]
         public ActionResult<AppProfileResource> Create(AppProfileResource resource)
         {
             var model = resource.ToModel();
@@ -28,12 +29,14 @@ namespace Prowlarr.Api.V1.Profiles.App
         }
 
         [RestDeleteById]
+        [Produces("application/json")]
         public void DeleteProfile(int id)
         {
             _profileService.Delete(id);
         }
 
         [RestPutById]
+        [Produces("application/json")]
         public ActionResult<AppProfileResource> Update(AppProfileResource resource)
         {
             var model = resource.ToModel();
@@ -43,12 +46,17 @@ namespace Prowlarr.Api.V1.Profiles.App
             return Accepted(model.Id);
         }
 
+        [Produces("application/json")]
+        [ProducesResponseType(typeof(AppProfileResource), 200)]
+        [ProducesResponseType(typeof(IDictionary<string, string>), 404)]
+        [ProducesResponseType(500)]
         public override AppProfileResource GetResourceById(int id)
         {
             return _profileService.Get(id).ToResource();
         }
 
         [HttpGet]
+        [Produces("application/json")]
         public List<AppProfileResource> GetAll()
         {
             return _profileService.All().ToResource();