chore: add docs

NostrServices.sln

@@ -6,6 +6,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 	ProjectSection(SolutionItems) = preProject
 		docker-compose.yml = docker-compose.yml
 		.drone.yml = .drone.yml
+		README.md = README.md
 	EndProjectSection
 EndProject
 Global

NostrServices/Controllers/ImportController.cs

@@ -21,6 +21,11 @@ public class ImportController : Controller
     /// <summary>
     /// Import events in ND-JSON format
     /// </summary>
+    /// <remarks>
+    /// POST events in ND-JSON format here to add them to the cache which is used in <see cref="OpenGraphController"/>
+    /// 
+    /// `nak req -k 1 -l 100 wss://nos.lol | curl -v -X POST --data-binary @- https://nostr.api.v0l.io/api/v1/import`
+    /// </remarks>
     /// <returns></returns>
     [HttpPost]
     [DisableRequestSizeLimit]

NostrServices/Controllers/LinkPreviewController.cs

@@ -29,8 +29,13 @@ public class LinkPreviewController : Controller
         _client.Timeout = TimeSpan.FromSeconds(30);
     }
 
+    /// <summary>
+    /// Fetch page and return parsed header tags
+    /// </summary>
+    /// <param name="url"></param>
+    /// <returns></returns>
     [HttpGet]
-    [ResponseCache(Duration = 21600, VaryByQueryKeys = new[] {"url"}, Location = ResponseCacheLocation.Any)]
+    [ResponseCache(Duration = 21600, VaryByQueryKeys = ["url"], Location = ResponseCacheLocation.Any)]
     public async Task<LinkPreviewData?> GetPreview([FromQuery] string url)
     {
         var urlHash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(url.ToLower())));
@@ -102,6 +107,7 @@ public class LinkPreviewController : Controller
 public class LinkPreviewData
 {
     [ProtoMember(1)]
+    [JsonIgnore]
     [System.Text.Json.Serialization.JsonIgnore]
     public List<KeyValuePair<string, string>> OgTags { get; init; } = new();
 

NostrServices/Controllers/OpenGraphController.cs

@@ -31,11 +31,15 @@ public class OpenGraphController : Controller
     /// <summary>
     /// Inject opengraph tags into provided html
     /// </summary>
-    /// <param name="id">Nostr identifier npub/note/nevent/naddr/nprofile</param>
+    /// <remarks>
+    /// POST your HTML content to this endpoint along with the ID of the content and the
+    /// returned HTML will contain OpenGraph tags relevant to the event/profile
+    /// </remarks>
+    /// <param name="id">Nostr identifier nip5/npub/note/nevent/naddr/nprofile</param>
     /// <param name="canonical">Url format for canonical tag <code>https://example.com/%s</code></param>
     /// <returns></returns>
     [HttpPost("{id}")]
-    [Consumes("text/html")]
+    [Consumes("text/html", "text/plain")]
     [Produces("text/html")]
     public async Task<IActionResult> TagPage([FromRoute] string id, [FromQuery] string? canonical)
     {

NostrServices/NostrServices.csproj

@@ -5,6 +5,8 @@
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <NoWarn>$(NoWarn);1591</NoWarn>
     </PropertyGroup>
 
     <ItemGroup>

NostrServices/Program.cs

@@ -1,4 +1,6 @@
+using System.Reflection;
 using Microsoft.EntityFrameworkCore;
+using Microsoft.OpenApi.Models;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Converters;
 using Newtonsoft.Json.Serialization;
@@ -46,7 +48,27 @@ public static class Program
         });
 
         builder.Services.AddEndpointsApiExplorer();
-        builder.Services.AddSwaggerGen();
+        builder.Services.AddSwaggerGen(opt =>
+        {
+            opt.SwaggerDoc("v1", new OpenApiInfo
+            {
+                Version = "v1",
+                Title = "NostrServices",
+                Description = "Nostr services",
+                Contact = new OpenApiContact
+                {
+                    Name = "v0l",
+                    Url = new Uri("https://snort.social/kieran")
+                },
+                License = new OpenApiLicense
+                {
+                    Name = "MIT",
+                    Url = new Uri("https://git.v0l.io/Kieran/NostrServices")
+                }
+            });
+            var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
+            opt.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
+        });
         builder.Services.AddHttpClient();
         builder.Services.AddMemoryCache();
         builder.Services.AddResponseCaching();

README.md

@@ -0,0 +1,8 @@
+# Nostr Services
+
+A set of API endpoints useful for nostr web clients
+
+https://nostr.api.v0l.io/swagger
+
+## License
+MIT