review feedback on docs

Author: maurei

docs/usage/openapi/openapi-generator.md renamed to docs/usage/openapi/api-description.md

@@ -1,4 +1,4 @@
-# OpenAPI generator
+# OpenAPI API Description
 
 You can describe your API with an OpenAPI specification using the [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) integration for JsonApiDotNetCore. 
 

docs/usage/openapi/client-generator.md renamed to docs/usage/openapi/client-library.md

@@ -1,6 +1,6 @@
-# Client Generator
+# OpenAPI Client Library
 
-You can you can generate a client library from an OpenAPI specification that describes a JsonApiDotNetCore application. For clients genearted with using [NSwag](http://stevetalkscode.co.uk/openapireference-commands) we provide an additional package that enables partial write requests.
+You can generate a client library 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 sending partial write requests.
 
 ## Installation
 
@@ -42,8 +42,8 @@ Add a reference to your OpenAPI specification in your project file as demonstrat
 ```xml
 <ItemGroup>
  <OpenApiReference Include="swagger.json">
-   <Namespace>ApiConsumer.GeneratedCode</Namespace>
-   <ClassName>OpenApiClient</ClassName>
+   <Namespace>JsonApiDotNetCoreExampleClient.GeneratedCode</Namespace>
+   <ClassName>ExampleApiClient</ClassName>
    <CodeGenerator>NSwagCSharp</CodeGenerator>
    <Options>/UseBaseUrl:false /GenerateClientInterfaces:true</Options>
  </OpenApiReference>
@@ -57,17 +57,17 @@ The NSwag tooling generates the OpenAPI client during a prebuild step. Once your
 you can instantiate it using the class name as indicated in the project file.
 
 ```c#
-namespace ApiConsumer
+namespace JsonApiDotNetCoreExampleClient
 {
     class Program
     {
         static void Main(string[] args)
         {
             using (HttpClient httpClient = new HttpClient())
             {
-                OpenApiClient openApiClient = new OpenApiClient(httpClient);
+                ExampleApiClient exampleApiClient = new ExampleApiClient(httpClient);
 
-                // IntelliSense is now available on `openApiClient`!
+                // IntelliSense is now available on `exampleApiClient`!
             }
         }
     }
@@ -77,10 +77,10 @@ namespace ApiConsumer
 Support for partial write requests can be enabled by leveraging the extensibility points of the generated client.
 
 ```c#
-// Note that this class should be namespace in which NSwag generates the client. 
-namespace ApiConsumer.GeneratedCode
+namespace JsonApiDotNetCoreExampleClient.GeneratedCode
 {
-    public partial class OpenApiClient : JsonApiClient
+    // Note that this class should be in the same namespace as the ExampleApiClient generated by NSwag. 
+    public partial class ExampleApiClient : JsonApiClient
     {
         partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings)
         {
@@ -98,34 +98,34 @@ static void Main(string[] args)
 {
     using (HttpClient httpClient = new HttpClient())
     {
-        OpenApiClient openApiClient = new OpenApiClient(httpClient);
+        ExampleApiClient exampleApiClient = new ExampleApiClient(httpClient);
 
-        var requestDocument = new ApiResourcePatchRequestDocument
+        var requestDocument = new PersonPatchRequestDocument
         {
-            Data = new ApiResourceDataInPatchRequest
+            Data = new PersonDataInPatchRequest
             {
-                Id = 543,
-                Type = ApiResourceResourceType.Airplanes,
-                Attributes = new ApiResourceAttributesInPatchRequest
+                Id = "546",
+                Type = PersonResourceType.People,
+                Attributes = new PersonAttributesInPatchRequest
                 {
-                    someNullableAttribute = "Value"
+                    FirstName = "Jack"
                 }
             }
         };
 
-        using (apiClient.RegisterAttributesForRequestDocument<ApiResourcePatchRequestDocument, ApiResourceDataInPatchRequest>(requestDocument, apiResource => apiResource.AnotherNullableAttribute)
+        using (apiClient.RegisterAttributesForRequestDocument<PersonPatchRequestDocument, PersonDataInPatchRequest>(requestDocument, person => person.LastName)
         {
-            await apiClient.PatchApiResourceAsync(543, requestDocument));
+            await exampleApiClient.PatchPersonAsync(543, requestDocument));
 
             // The request will look like this:
             //
             // {
             //   "data": {
-            //     "type": "apiResource",
+            //     "type": "people",
             //     "id": "543",
             //     "attributes": {
-            //       "someNullableAttribute": "Value",
-            //       "anotherNullableAttribute": null,
+            //       "firstName": "Jack",
+            //       "lastName": null,
             //     }
             //   }
             // }

docs/usage/toc.md

@@ -23,8 +23,8 @@
 # [Caching](caching.md)
 
 # OpenAPI
-## [Describing Your API](openapi/openapi-generator.md))
-## [Generating A Client](openapi/client-generator.md))
+## [API Description](openapi/api-description.md))
+## [Client Library](openapi/client-library.md))
 
 # Extensibility
 ## [Layer Overview](extensibility/layer-overview.md)