actually testing docs endpoint. this will require you to generate the docs on first run / change

documenting this and the build as well

Author: thefringeninja

README.md

@@ -4,6 +4,14 @@ Fully RESTful HTTP Server for [SQL Stream Store](https://github.com/SQLStreamSto
 
 The solution includes example of use  LittleHalHost.Example project. The url structure and parameters are described in LittleHalHost.Example/readme.md
 
+# Development
+
+- `./build.sh` or `./build.cmd` to run the complete dockerized build.
+- `dotnet run --project build/build.csproj` to build without using docker.
+To see a list of build targets, `dotnet run --project build/build.csproj -- --list-targets`.
+For general help with the build, `dotnet run --project build/build.csproj -- --help`.
+- If you are running test from your IDE, you _must_ build with the `GenerateDocumentation` target at least once, otherwise the tests around documentation will fail.
+
 # Clients
 
 - [Official dotnet client](https://github.com/SQLStreamStore/SQLStreamStore)
@@ -15,4 +23,4 @@ Ask questions in the `#sql-stream-store` channel in the [ddd-cqrs-es slack](http
 
 # Licences
 
-Licenced under [MIT](LICENSE).
+Licenced under [MIT](LICENSE).

src/SqlStreamStore.HAL.Tests/AllJsonSchemasTests.cs

@@ -41,7 +41,7 @@ where s_isSqlStreamStoreSchema.IsMatch(manifestName)
         public async Task byte_order_mark_not_present(string manifestName)
         {
             byte[] firstThreeBytes = new byte[3];
-            
+
             using(var stream = GetStream(manifestName))
             {
                 await stream.ReadAsync(firstThreeBytes);

src/SqlStreamStore.HAL.Tests/DocumentationTests.cs

@@ -0,0 +1,89 @@
+namespace SqlStreamStore.HAL.Tests
+{
+    using System;
+    using System.Collections.Generic;
+    using System.IO;
+    using System.Linq;
+    using System.Net;
+    using System.Net.Http;
+    using System.Net.Http.Headers;
+    using System.Threading.Tasks;
+    using Shouldly;
+    using SqlStreamStore.HAL.StreamMessage;
+    using SqlStreamStore.HAL.StreamMetadata;
+    using SqlStreamStore.HAL.Streams;
+    using Xunit;
+
+    public class DocumentationTests : IDisposable
+    {
+        private static readonly MediaTypeWithQualityHeaderValue[] s_MarkdownMediaTypes =
+        {
+            new MediaTypeWithQualityHeaderValue(Constants.MediaTypes.TextMarkdown), 
+            new MediaTypeWithQualityHeaderValue(Constants.MediaTypes.TextMarkdown)
+            {
+                CharSet = "utf-8"
+            },
+            new MediaTypeWithQualityHeaderValue(Constants.MediaTypes.Any) 
+        };
+        private static readonly IDictionary<string, Type> s_documentedRels = new Dictionary<string, Type>
+        {
+            ["append"] = typeof(StreamResource),
+            ["delete-stream"] = typeof(StreamResource),
+            ["delete-message"] = typeof(StreamMessageResource),
+            ["metadata"] = typeof(StreamMetadataResource)
+        };
+
+        private readonly SqlStreamStoreHalMiddlewareFixture _fixture;
+
+        public DocumentationTests()
+        {
+            _fixture = new SqlStreamStoreHalMiddlewareFixture();
+        }
+
+        public static IEnumerable<object[]> DocumentationCases()
+            => from pair in s_documentedRels
+                from mediaType in s_MarkdownMediaTypes
+                select new object[]
+                {
+                    pair.Key,
+                    mediaType,
+                    pair.Value.Assembly.GetManifestResourceStream(pair.Value, $"Schema.{pair.Key}.schema.md")
+                };
+
+        [Fact]
+        public async Task documentation_not_found()
+        {
+            using(var response = await _fixture.HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Get, $"/docs/{Guid.NewGuid()}")
+            {
+                Headers = { Accept = { MediaTypeWithQualityHeaderValue.Parse(Constants.MediaTypes.TextMarkdown) } }
+            }))
+            {
+                response.StatusCode.ShouldBe(HttpStatusCode.NotFound);
+            }
+        }
+
+        [Theory, MemberData(nameof(DocumentationCases))]
+        public async Task documentation(string rel, MediaTypeWithQualityHeaderValue accept, Stream content)
+        {
+            content.ShouldNotBeNull();
+            
+            using (var expectedDocument = new MemoryStream())
+            using (var actualDocument = new MemoryStream())
+            using(var response = await _fixture.HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Get, $"/docs/{rel}")
+            {
+                Headers = { Accept = { accept } }
+            }))
+            {
+                response.StatusCode.ShouldBe(HttpStatusCode.OK);
+
+                await content.CopyToAsync(expectedDocument);
+
+                await response.Content.CopyToAsync(actualDocument);
+                
+                expectedDocument.ToArray().ShouldBe(actualDocument.ToArray());
+            }
+        }
+
+        public void Dispose() => _fixture.Dispose();
+    }
+}

src/SqlStreamStore.HAL/Constants.cs

@@ -9,7 +9,7 @@ internal static class Constants
     {
         public static class MediaTypes
         {
-            public const string TextMarkdown = "text/markdown; charset=UTF-8";
+            public const string TextMarkdown = "text/markdown";
             public const string HalJson = "application/hal+json";
             public const string Any = "*/*";
         }

src/SqlStreamStore.HAL/MarkdownResponse.cs

@@ -1,16 +1,23 @@
 namespace SqlStreamStore.HAL
 {
     using System.IO;
+    using System.Net.Http.Headers;
     using System.Threading;
     using System.Threading.Tasks;
     using Microsoft.AspNetCore.Http;
 
     internal class MarkdownResponse : Response
     {
+        private static readonly string s_TextMarkdown
+            = new MediaTypeHeaderValue(Constants.MediaTypes.TextMarkdown)
+            {
+                CharSet = "utf-8"
+            }.ToString();
+
         private readonly Stream _body;
 
         public MarkdownResponse(Stream body)
-            : base(body == null ? 404 : 200, Constants.MediaTypes.TextMarkdown)
+            : base(body == null ? 404 : 200, s_TextMarkdown)
         {
             _body = body;
         }