-
-
Notifications
You must be signed in to change notification settings - Fork 159
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move existing integration to JADNC (#1076)
* Copied integration and fixed compilation errors * Add models and adjusted models in OpenAPI document tests such that i reflect features that were covered in the private repository * Add FlightAttendantController to used controllers * Added client library with tests to project; made adjustmets to the models to make the client test pass without introducing any structural adjustments to the test codes * Adjusted build script to create OpenApiClient artifact, added documentation, minor model adjustments * Adjusted docs and minor refactors * Replace resource name formatter with internal one * Removed JsonApiInputFormatter workaround * Moved full document test to ExistingOpenApiIntegration test folder, which is to be removed at the very end once have dedicated test suites for all components * Disabled OpenAPI for nonjson and operations controller, as these are not yet supported and will cause the integration to crash * review feedback on docs * Add a very minimal example of a generated OpenAPI client for JsonApiDotNetCoreExample project. The only call that currently doesn't crash is the one associated to deleting a primary resource * Fixed inspect and cleanup code issues that do not appear when executed through Rider * rename existing to legacy in ExistingOpenApiIntegration folder and namespace * moved OpenApiClient to OpenApi.Client * Configure NSwag to generate a client with access modifier set to internal. Simplified ExampleApiClient to not use a generated interface * Move OpenAPI client tests to dedicated test project, cleared up some unrequired internalsVisibleTo usage * Some adjustments to stay closer to 1-on-1 model mapping from the private repository of the legacy integration. Also processed some of the review feedback * review feedback * Process inspectcode issues that do not appear when run locally * Update package reference in build script * Changed models to stay closer 1-to-1 mapping. Changed 'OpenApiClient' to 'OpenApi.Client'. Removed unneeded config from legacy integration startup. * process review feedback * rename ClassName in client test project * Updated example client project using Visual Studio defaults and updated documentation * Layout tweaks and fixes * fixed failed automatic rename 'openApiOpenApi' * reduced changed wrt private version of this test * Changed ID type from to for Flight * ReserveCabinPersonnel -> Purser, CabinPersonnel -> CabinCrewMembers * fixed failed automatic rename 'openApiOpenApi' * Flight: replaced OperatingAirplane with Purser, added to many relationship to new model Passenger * Review feedback * Fix client lifetime test * Feedback Co-authored-by: Bart Koelman <bart@degreed.com>
- Loading branch information
Showing
109 changed files
with
11,189 additions
and
1,078 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,139 @@ | ||
| # OpenAPI Client | ||
|
|
||
| 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 | ||
|
|
||
| ### Visual Studio | ||
|
|
||
| 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(); | ||
|
|
||
| foreach (PersonDataInResponse person in getResponse.Data) | ||
| { | ||
| 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; | ||
|
|
||
| partial class ExampleApiClient : JsonApiClient | ||
| { | ||
| partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings) | ||
| { | ||
| SetSerializerSettingsForJsonApi(settings); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 7. Extend your demo code to send a partial PATCH request with the help of our package: | ||
|
|
||
| ```c# | ||
| var patchRequest = new PersonPatchRequestDocument | ||
| { | ||
| Data = new PersonDataInPatchRequest | ||
| { | ||
| Id = "1", | ||
| Attributes = new PersonAttributesInPatchRequest | ||
| { | ||
| FirstName = "Jack" | ||
| } | ||
| } | ||
| }; | ||
|
|
||
| // This line results in sending "lastName: null" instead of omitting it. | ||
| using (apiClient.RegisterAttributesForRequestDocument<PersonPatchRequestDocument, | ||
| PersonAttributesInPatchRequest>(patchRequest, person => person.LastName)) | ||
| { | ||
| PersonPrimaryResponseDocument patchResponse = | ||
| await apiClient.PatchPersonAsync("1", patchRequest); | ||
|
|
||
| // The sent request looks like this: | ||
| // { | ||
| // "data": { | ||
| // "type": "people", | ||
| // "id": "1", | ||
| // "attributes": { | ||
| // "firstName": "Jack", | ||
| // "lastName": null | ||
| // } | ||
| // } | ||
| // } | ||
| } | ||
| ``` | ||
|
|
||
| ### Other IDEs | ||
|
|
||
| When using the command-line, you can try the [Microsoft.dotnet-openapi Global Tool](https://docs.microsoft.com/en-us/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-5.0). | ||
| Alternatively, the next section shows what to add to your client project file directly: | ||
|
|
||
| ```xml | ||
| <ItemGroup> | ||
| <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="3.0.0"> | ||
| <PrivateAssets>all</PrivateAssets> | ||
| <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> | ||
| </PackageReference> | ||
| <PackageReference Include="Newtonsoft.Json" Version="12.0.2" /> | ||
| <PackageReference Include="NSwag.ApiDescription.Client" Version="13.0.5"> | ||
| <PrivateAssets>all</PrivateAssets> | ||
| <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> | ||
| </PackageReference> | ||
| </ItemGroup> | ||
|
|
||
| <ItemGroup> | ||
| <OpenApiReference Include="OpenAPIs\swagger.json" CodeGenerator="NSwagCSharp" ClassName="ExampleApiClient"> | ||
| <SourceUri>http://localhost:14140/swagger/v1/swagger.json</SourceUri> | ||
| </OpenApiReference> | ||
| </ItemGroup> | ||
| ``` | ||
|
|
||
| From here, continue from step 3 in the list of steps for Visual Studio. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### NSwag | ||
|
|
||
| The `OpenApiReference` element in the project file accepts an `Options` element to pass additional settings to the client generator, | ||
| 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.GeneratedCode</Namespace> | ||
| <ClassName>SalesApiClient</ClassName> | ||
| <CodeGenerator>NSwagCSharp</CodeGenerator> | ||
| <Options>/UseBaseUrl:false /GenerateClientInterfaces:true</Options> | ||
| </OpenApiReference> | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
15 changes: 15 additions & 0 deletions
15
src/Examples/JsonApiDotNetCoreExampleClient/ExampleApiClient.cs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| using JsonApiDotNetCore.OpenApi.Client; | ||
| using Newtonsoft.Json; | ||
|
|
||
| namespace JsonApiDotNetCoreExampleClient | ||
| { | ||
| public partial class ExampleApiClient : JsonApiClient | ||
| { | ||
| partial void UpdateJsonSerializerSettings(JsonSerializerSettings settings) | ||
| { | ||
| SetSerializerSettingsForJsonApi(settings); | ||
|
|
||
| settings.Formatting = Formatting.Indented; | ||
| } | ||
| } | ||
| } |
28 changes: 28 additions & 0 deletions
28
src/Examples/JsonApiDotNetCoreExampleClient/JsonApiDotNetCoreExampleClient.csproj
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| <Project Sdk="Microsoft.NET.Sdk"> | ||
| <PropertyGroup> | ||
| <OutputType>Exe</OutputType> | ||
| <TargetFramework>$(NetCoreAppVersion)</TargetFramework> | ||
| </PropertyGroup> | ||
|
|
||
| <ItemGroup> | ||
| <ProjectReference Include="..\..\JsonApiDotNetCore.OpenApi.Client\JsonApiDotNetCore.OpenApi.Client.csproj" /> | ||
| </ItemGroup> | ||
|
|
||
| <ItemGroup> | ||
| <PackageReference Include="Microsoft.Extensions.ApiDescription.Client" Version="5.0.10"> | ||
| <PrivateAssets>all</PrivateAssets> | ||
| <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> | ||
| </PackageReference> | ||
| <PackageReference Include="Newtonsoft.Json" Version="13.0.1" /> | ||
| <PackageReference Include="NSwag.ApiDescription.Client" Version="13.13.2"> | ||
| <PrivateAssets>all</PrivateAssets> | ||
| <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets> | ||
| </PackageReference> | ||
| </ItemGroup> | ||
|
|
||
| <ItemGroup> | ||
| <OpenApiReference Include="OpenAPIs\swagger.json" CodeGenerator="NSwagCSharp" ClassName="ExampleApiClient"> | ||
| <SourceUri>http://localhost:14140/swagger/v1/swagger.json</SourceUri> | ||
| </OpenApiReference> | ||
| </ItemGroup> | ||
| </Project> |
Oops, something went wrong.