Layout tweaks and fixes

Author: Bart Koelman

docs/usage/openapi-client.md

@@ -1,6 +1,8 @@
 # OpenAPI Client
 
-You can generate a JSON:API client in various programming languages from the OpenAPI specification file that JsonApiDotNetCore APIs provide. For C# .NET clients generated using NSwag, we provide an additional package that introduces support for partial PATCH/POST requests. The issue here is that a property on a generated C# class being `null` could mean "set the value to `null` in the request" or "this is `null` because I never touched it".
+You can generate a JSON:API client in various programming languages from the [OpenAPI specification](https://swagger.io/specification/) file that JsonApiDotNetCore APIs provide.
+
+For C# .NET clients generated using [NSwag](https://github.com/RicoSuter/NSwag), we provide an additional package that introduces support for partial PATCH/POST requests. The issue here is that a property on a generated C# class being `null` could mean "set the value to `null` in the request" or "this is `null` because I never touched it".
 
 ## Getting started
 
@@ -9,28 +11,38 @@ You can generate a JSON:API client in various programming languages from the Ope
 The easiest way to get started is by using the built-in capabilities of Visual Studio. The next steps describe how to generate a JSON:API client library and use our package.
 
 1.  In **Solution Explorer**, right-click your client project, select **Add** > **Service Reference** and choose **OpenAPI**.
+
 2.  On the next page, specify the OpenAPI URL to your JSON:API server, for example: `http://localhost:14140/swagger/v1/swagger.json`.
     Optionally provide a class name and namespace and click **Finish**.
     Visual Studio now downloads your swagger.json and updates your project file. This results in a pre-build step that generates the client code.
+
     Tip: To later re-download swagger.json and regenerate the client code, right-click **Dependencies** > **Manage Connected Services** and click the **Refresh** icon.
 3.  Although not strictly required, we recommend to run package update now, which fixes some issues and removes the `Stream` parameter from generated calls.
+
 4.  Add some demo code that calls one of your JSON:API endpoints. For example:
+
     ```c#
     using var httpClient = new HttpClient();
     var apiClient = new ExampleApiClient("http://localhost:14140", httpClient);
 
-    PersonCollectionResponseDocument getResponse = await apiClient.GetPersonCollectionAsync();
+    PersonCollectionResponseDocument getResponse =
+        await apiClient.GetPersonCollectionAsync();
 
     foreach (PersonDataInResponse person in getResponse.Data)
     {
-        Console.WriteLine($"Found user {person.Id} named '{person.Attributes.FirstName} {person.Attributes.LastName}'.");
+        Console.WriteLine($"Found user {person.Id} named " +
+            $"'{person.Attributes.FirstName} {person.Attributes.LastName}'.");
     }
     ```
+
 5.  Add our client package to your project:
+
    ```
    dotnet add package JsonApiDotNetCore.OpenApi.Client
    ```
+
 6.  Add the following glue code to connect our package with your generated code. The code below assumes you specified `ExampleApiClient` as class name in step 2.
+
     ```c#
     using JsonApiDotNetCore.OpenApi.Client;
     using Newtonsoft.Json;
@@ -43,7 +55,9 @@ The easiest way to get started is by using the built-in capabilities of Visual S
         }
     }
     ```
+
 7.  Extend your demo code to send a partial PATCH request with the help of our package:
+
     ```c#
     var patchRequest = new PersonPatchRequestDocument
     {
@@ -58,10 +72,11 @@ The easiest way to get started is by using the built-in capabilities of Visual S
     };
 
     // This line results in sending "lastName: null" instead of omitting it.
-    using (apiClient.RegisterAttributesForRequestDocument<PersonPatchRequestDocument, PersonAttributesInPatchRequest>(
-        patchRequest, person => person.LastName))
+    using (apiClient.RegisterAttributesForRequestDocument<PersonPatchRequestDocument,
+        PersonAttributesInPatchRequest>(patchRequest, person => person.LastName))
     {
-        PersonPrimaryResponseDocument patchResponse = await apiClient.PatchPersonAsync("1", patchRequest);
+        PersonPrimaryResponseDocument patchResponse =
+            await apiClient.PatchPersonAsync("1", patchRequest);
 
         // The sent request looks like this:
         // {
@@ -105,17 +120,18 @@ Alternatively, the next section shows what to add to your client project file di
 
 From here, continue from step 3 in the list of steps for Visual Studio.
 
-## Customization
+## Configuration
 
-### NSwga
+### NSwag
 
 The `OpenApiReference` element in the project file accepts an `Options` element to pass additional settings to the client generator,
-which are listed at https://github.com/RicoSuter/NSwag/blob/master/src/NSwag.Commands/Commands/CodeGeneration/OpenApiToCSharpClientCommand.cs.
+which are listed [here](https://github.com/RicoSuter/NSwag/blob/master/src/NSwag.Commands/Commands/CodeGeneration/OpenApiToCSharpClientCommand.cs).
 
 For example, the next section puts the generated code in a namespace, removes the `baseUrl` parameter and generates an interface (which is handy for dependency injection):
+
 ```xml
 <OpenApiReference Include="swagger.json">
-  <Namespace>ExampleProject.ServiceAccess.GeneratedCode</Namespace>
+  <Namespace>ExampleProject.GeneratedCode</Namespace>
   <ClassName>SalesApiClient</ClassName>
   <CodeGenerator>NSwagCSharp</CodeGenerator>
   <Options>/UseBaseUrl:false /GenerateClientInterfaces:true</Options>

docs/usage/openapi.md

@@ -3,63 +3,47 @@
 JsonApiDotNetCore provides an extension package that enables you to produce an [OpenAPI specification](https://swagger.io/specification/) for your JSON:API endpoints. This can be used to generate a [documentation website](https://swagger.io/tools/swagger-ui/) or to generate [client libraries](https://openapi-generator.tech/docs/generators/) in various languages. The package provides an integration with [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore).
 
 
-## Installation
+## Getting started
 
-Install the `JsonApiDotNetCore.OpenApi` NuGet package.
+1.  Install the `JsonApiDotNetCore.OpenApi` NuGet package:
 
-### CLI
+    ```
+    dotnet add package JsonApiDotNetCore.OpenApi
+    ```
 
-```
-dotnet add package JsonApiDotNetCore.OpenApi
-```
-
-### Visual Studio
-
-```powershell
-Install-Package JsonApiDotNetCore.OpenApi
-```
-
-### *.csproj
-
-```xml
-<ItemGroup>
-  <!-- Be sure to check NuGet for the latest version # -->
-  <PackageReference Include="JsonApiDotNetCore.OpenApi" Version="4.0.0" />
-</ItemGroup>
-```
-
-## Usage
+2.  Add the integration in your `Startup` class.
 
-Add the integration in your `Startup` class.
-
-```c#
-public class Startup
-{
-    public void ConfigureServices(IServiceCollection services)
+    ```c#
+    public class Startup
     {
-        IMvcCoreBuilder mvcBuilder = services.AddMvcCore();
-        services.AddJsonApi<AppDbContext>(mvcBuilder: mvcBuilder);
+        public void ConfigureServices(IServiceCollection services)
+        {
+            IMvcCoreBuilder mvcBuilder = services.AddMvcCore();
 
-        // Adds the Swashbuckle integration.
-        services.AddOpenApi(mvcBuilder);
-    }
+            services.AddJsonApi<AppDbContext>(mvcBuilder: mvcBuilder);
 
-    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
-    {
-        app.UseRouting();
-        app.UseJsonApi();
+            // Adds the Swashbuckle integration.
+            services.AddOpenApi(mvcBuilder);
+        }
+
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+        {
+            app.UseRouting();
+            app.UseJsonApi();
         
-        // Adds the Swashbuckle middleware.
-        app.UseSwagger();
+            // Adds the Swashbuckle middleware.
+            app.UseSwagger();
 
-        app.UseEndpoints(endpoints => endpoints.MapControllers());
+            app.UseEndpoints(endpoints => endpoints.MapControllers());
+        }
     }
-}
-```
+    ```
 
 By default, the OpenAPI specification will be available at `http://localhost:<port>/swagger/v1/swagger.json`.
 
-Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), tooling for a generated documentation page. This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Startup` class.
+## Documentation
+
+Swashbuckle also ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), tooling for a generated documentation page. This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Startup` class:
 
 ```c#
 // Startup.cs

docs/usage/toc.md

@@ -22,8 +22,8 @@
 # [Metadata](meta.md)
 # [Caching](caching.md)
 
-# [OpenAPI](openapi.md))
-## [Client](openapi-client.md))
+# [OpenAPI](openapi.md)
+## [Client](openapi-client.md)
 
 # Extensibility
 ## [Layer Overview](extensibility/layer-overview.md)