Skip to content

Commit c6d691d

Browse files
committed
Adjusted docs and minor refactors
1 parent ec2ccaf commit c6d691d

File tree

15 files changed

+154
-114
lines changed

15 files changed

+154
-114
lines changed
Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Client Generator
2+
3+
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.
4+
5+
## Installation
6+
7+
You are required to install the following NuGet packages:
8+
9+
- `JsonApiDotNetCore.OpenApiClient`
10+
- `NSwag.ApiDescription.Client`
11+
- `Microsoft.Extensions.ApiDescription.Cient`
12+
- `NSwag.ApiDescription.Client`
13+
14+
The following examples demonstrate how to install the `JsonApiDotNetCore.OpenApiClient` package.
15+
16+
### CLI
17+
18+
```
19+
dotnet add package JsonApiDotNetCore.OpenApiClient
20+
```
21+
22+
### Visual Studio
23+
24+
```powershell
25+
Install-Package JsonApiDotNetCore.OpenApiClient
26+
```
27+
28+
### *.csproj
29+
30+
```xml
31+
<ItemGroup>
32+
<!-- Be sure to check NuGet for the latest version # -->
33+
<PackageReference Include="JsonApiDotNetCore.OpenApiClient" Version="4.0.0" />
34+
</ItemGroup>
35+
```
36+
37+
38+
## Adding an OpenApiReference
39+
40+
Add a reference to your OpenAPI specification in your project file as demonstrated below.
41+
42+
```xml
43+
<ItemGroup>
44+
<OpenApiReference Include="swagger.json">
45+
<Namespace>ApiConsumer.GeneratedCode</Namespace>
46+
<ClassName>OpenApiClient</ClassName>
47+
<CodeGenerator>NSwagCSharp</CodeGenerator>
48+
<Options>/UseBaseUrl:false /GenerateClientInterfaces:true</Options>
49+
</OpenApiReference>
50+
</ItemGroup>
51+
```
52+
53+
54+
## Usage
55+
56+
The NSwag tooling generates the OpenAPI client during a prebuild step. Once your application is built,
57+
you can instantiate it using the class name as indicated in the project file.
58+
59+
```c#
60+
namespace ApiConsumer
61+
{
62+
class Program
63+
{
64+
static void Main(string[] args)
65+
{
66+
using (HttpClient httpClient = new HttpClient())
67+
{
68+
OpenApiClient openApiClient = new OpenApiClient(httpClient);
69+
70+
// IntelliSense is now available on `openApiClient`!
71+
}
72+
}
73+
}
74+
}
75+
```
76+
77+
Support for partial write requests can be enabled by leveraging the extensibility points of the generated client.
78+
79+
```c#
80+
// Note that this class should be namespace in which NSwag generates the client.
81+
namespace ApiConsumer.GeneratedCode
82+
{
83+
public partial class OpenApiClient : JsonApiClient
84+
{
85+
partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings)
86+
{
87+
SetSerializerSettingsForJsonApi(settings);
88+
}
89+
}
90+
}
91+
```
92+
93+
You can now perform a write request by calling the `RegisterAttributesForRequest` method. Calling this method treats all attributes that contain their default value (<c>null</c> for reference types, <c>0</c> for integers, <c>false</c> for booleans, etc) as omitted unless explicitly listed to include them using the `alwaysIncludedAttributeSelectors` parameter.
94+
95+
```c#
96+
// Program.cs
97+
static void Main(string[] args)
98+
{
99+
using (HttpClient httpClient = new HttpClient())
100+
{
101+
OpenApiClient openApiClient = new OpenApiClient(httpClient);
102+
103+
var requestDocument = new ApiResourcePatchRequestDocument
104+
{
105+
Data = new ApiResourceDataInPatchRequest
106+
{
107+
Id = 543,
108+
Type = ApiResourceResourceType.Airplanes,
109+
Attributes = new ApiResourceAttributesInPatchRequest
110+
{
111+
someNullableAttribute = "Value"
112+
}
113+
}
114+
};
115+
116+
using (apiClient.RegisterAttributesForRequestDocument<ApiResourcePatchRequestDocument, ApiResourceDataInPatchRequest>(requestDocument, apiResource => apiResource.AnotherNullableAttribute)
117+
{
118+
await apiClient.PatchApiResourceAsync(543, requestDocument));
119+
120+
// The request will look like this:
121+
//
122+
// {
123+
// "data": {
124+
// "type": "apiResource",
125+
// "id": "543",
126+
// "attributes": {
127+
// "someNullableAttribute": "Value",
128+
// "anotherNullableAttribute": null,
129+
// }
130+
// }
131+
// }
132+
}
133+
134+
}
135+
}
136+
```
137+

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# OpenAPI
1+
# OpenAPI generator
22

33
You can describe your API with an OpenAPI specification using the [Swashbuckle](https://github.com/domaindrivendev/Swashbuckle.AspNetCore) integration for JsonApiDotNetCore.
44

docs/usage/openapi/openapiclient.md

Lines changed: 0 additions & 79 deletions
This file was deleted.

docs/usage/toc.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@
2323
# [Caching](caching.md)
2424

2525
# OpenAPI
26-
## [Specification Generator](openapi/openapi.md))
27-
## [Generated Client](openapi/openapiclient.md))
26+
## [Describing Your API](openapi/openapi-generator.md))
27+
## [Generating A Client](openapi/client-generator.md))
2828

2929
# Extensibility
3030
## [Layer Overview](extensibility/layer-overview.md)

src/JsonApiDotNetCore.OpenApi/JsonApiActionDescriptorCollectionProvider.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
using System.Collections.Generic;
33
using System.Linq;
44
using System.Reflection;
5-
using JsonApiDotNetCore.OpenApi.JsonApiMetadata;
65
using JsonApiDotNetCore.Configuration;
76
using JsonApiDotNetCore.Middleware;
7+
using JsonApiDotNetCore.OpenApi.JsonApiMetadata;
88
using Microsoft.AspNetCore.Mvc;
99
using Microsoft.AspNetCore.Mvc.Abstractions;
1010
using Microsoft.AspNetCore.Mvc.Controllers;

src/JsonApiDotNetCore.OpenApi/JsonApiMetadata/JsonApiEndpointMetadataProvider.cs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
using System.Collections.Generic;
33
using System.Linq;
44
using System.Reflection;
5-
using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
6-
using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
75
using JsonApiDotNetCore.Configuration;
86
using JsonApiDotNetCore.Middleware;
7+
using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
8+
using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
99
using JsonApiDotNetCore.Resources.Annotations;
1010

1111
namespace JsonApiDotNetCore.OpenApi.JsonApiMetadata

src/JsonApiDotNetCore.OpenApi/JsonApiOperationIdSelector.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
using System.Collections.Generic;
33
using System.Linq;
44
using Humanizer;
5+
using JsonApiDotNetCore.Middleware;
56
using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
67
using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
7-
using JsonApiDotNetCore.Middleware;
88
using Microsoft.AspNetCore.Mvc;
99
using Microsoft.AspNetCore.Mvc.ApiExplorer;
1010
using Microsoft.AspNetCore.Mvc.Controllers;

src/JsonApiDotNetCore.OpenApi/JsonApiSchemaIdSelector.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
using System.Collections.Generic;
33
using System.Linq;
44
using Humanizer;
5+
using JsonApiDotNetCore.Configuration;
56
using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
67
using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
78
using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
8-
using JsonApiDotNetCore.Configuration;
99

1010
namespace JsonApiDotNetCore.OpenApi
1111
{

src/JsonApiDotNetCore.OpenApi/SwaggerComponents/JsonApiSchemaGenerator.cs

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
using System;
22
using System.Linq;
33
using System.Reflection;
4+
using JsonApiDotNetCore.Configuration;
45
using JsonApiDotNetCore.OpenApi.JsonApiObjects;
56
using JsonApiDotNetCore.OpenApi.JsonApiObjects.Documents;
67
using JsonApiDotNetCore.OpenApi.JsonApiObjects.RelationshipData;
7-
using JsonApiDotNetCore.Configuration;
88
using Microsoft.OpenApi.Models;
99
using Swashbuckle.AspNetCore.SwaggerGen;
1010

@@ -66,16 +66,9 @@ public OpenApiSchema GenerateSchema(Type type, SchemaRepository schemaRepository
6666
return jsonApiDocumentSchema;
6767
}
6868

69-
OpenApiSchema schema;
70-
71-
if (IsJsonApiResourceDocument(type))
72-
{
73-
schema = GenerateResourceJsonApiDocumentSchema(type);
74-
}
75-
else
76-
{
77-
schema = _defaultSchemaGenerator.GenerateSchema(type, schemaRepository, memberInfo, parameterInfo);
78-
}
69+
OpenApiSchema schema = IsJsonApiResourceDocument(type)
70+
? GenerateResourceJsonApiDocumentSchema(type)
71+
: _defaultSchemaGenerator.GenerateSchema(type, schemaRepository, memberInfo, parameterInfo);
7972

8073
if (IsSingleNonPrimaryDataDocument(type))
8174
{

src/JsonApiDotNetCore.OpenApi/SwaggerComponents/ResourceObjectSchemaGenerator.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
using System;
22
using System.Collections.Generic;
3-
using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
43
using JsonApiDotNetCore.Configuration;
4+
using JsonApiDotNetCore.OpenApi.JsonApiObjects.ResourceObjects;
55
using Microsoft.OpenApi.Models;
66
using Newtonsoft.Json.Serialization;
77
using Swashbuckle.AspNetCore.SwaggerGen;

0 commit comments

Comments
 (0)