-
-
Notifications
You must be signed in to change notification settings - Fork 158
Move existing integration to JADNC #1076
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
37 commits
Select commit
Hold shift + click to select a range
1c099e7
Copied integration and fixed compilation errors
maurei 54a023f
Add models and adjusted models in OpenAPI document tests such that i …
maurei 09ab5c0
Add FlightAttendantController to used controllers
maurei 19cc14d
Added client library with tests to project; made adjustmets to the mo…
maurei ec2ccaf
Adjusted build script to create OpenApiClient artifact, added documen…
maurei c6d691d
Adjusted docs and minor refactors
maurei ef2753e
Replace resource name formatter with internal one
maurei b3cdc7a
Removed JsonApiInputFormatter workaround
maurei a955616
Merge branch 'openapi' into oa/existing-integration
maurei bad9aad
Moved full document test to ExistingOpenApiIntegration test folder, w…
maurei ea46194
Disabled OpenAPI for nonjson and operations controller, as these are …
maurei a0d5bff
review feedback on docs
maurei 280e449
Add a very minimal example of a generated OpenAPI client for JsonApiD…
maurei 7b3d1ef
Fixed inspect and cleanup code issues that do not appear when execute…
maurei ba42b77
rename existing to legacy in ExistingOpenApiIntegration folder and na…
maurei ecd971e
moved OpenApiClient to OpenApi.Client
maurei 37a95b3
Configure NSwag to generate a client with access modifier set to inte…
maurei da1db37
Move OpenAPI client tests to dedicated test project, cleared up some …
maurei f71bbea
Some adjustments to stay closer to 1-on-1 model mapping from the priv…
maurei 348dffa
review feedback
maurei e88c762
Process inspectcode issues that do not appear when run locally
maurei 54ac898
Update package reference in build script
maurei 83ac507
Changed models to stay closer 1-to-1 mapping. Changed 'OpenApiClient…
maurei aaf59a6
process review feedback
maurei 1baed2d
rename ClassName in client test project
maurei 65430a8
Updated example client project using Visual Studio defaults and updat…
520c618
Layout tweaks and fixes
b72d823
fixed failed automatic rename 'openApiOpenApi'
maurei 43cec51
Merge branch 'oa/existing-integration' of https://github.com/json-api…
maurei 605d2ce
reduced changed wrt private version of this test
maurei 8c2a7b4
Changed ID type from to for Flight
maurei a83de89
ReserveCabinPersonnel -> Purser, CabinPersonnel -> CabinCrewMembers
maurei 8ceff7b
fixed failed automatic rename 'openApiOpenApi'
maurei 5a4a06f
Flight: replaced OperatingAirplane with Purser, added to many relatio…
maurei 7a88a64
Review feedback
maurei 4073c3f
Fix client lifetime test
maurei d3ebfaf
Feedback
maurei File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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 hidden or 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 hidden or 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 hidden or 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 hidden or 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 hidden or 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 hidden or 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.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.