This is not one of my usual blogs, but an aide-mémoire for myself that may be of use to other people who are using the OpenApiReference tooling in their C# projects to generate C# client code for HTTP APIs from Swagger/OpenApi definitions.
I have been using Rico Suter’s brilliant NSwag for some time now to generate client code for working with HTTP API endpoints. Initially I was using the NSwag Studio application to create the C# code and placing the output into my project, but then I later found I could add the code generation into build process using the NSwag MSBuild task.
Recently though, I watched the ASP.NET Community Standup with Jon Galloway and Brady Gaster. In the last half hour or so, they discuss the Connected Services functionality in Visual Studio 2019 that sets up code generation of HTTP API endpoint clients for you.
This feature had passed me by and watching the video got my curiosity going as to whether the build chain that I have been using for the last couple of years could be simplified. Especially given that, behind the scenes, it is using NSwag to do the code generation.
Using Connected Services
Having watched the video above, I recommend reading Jon Galloway’s post Generating HTTP API clients using Visual Studio Connected Services As that post covers the introduction to using Connected Services, I won’t repeat the basics again here.
It is also worth reading the other blog posts in the series written by Brady Gaster:
- Creating Discoverable HTTP APIs with ASP.NET Core 5 Web API
- Open-source HTTP API packages and tools
- App Building with Azure API Management, Functions, Power Apps, and Logic Apps
One of the new things I learnt from the video and blog posts is to make sure that your OpenApi definitions in the source API include an OperationId (which you can set by overloads of the HttpGet, HttpPost (etc) attributes on your Action method) to help the code generator assign a ‘sensible’ names to the calling method in the code generated client.
Purpose of This Post
Having started with using the Visual Studio dialogs to set up the Connected Service, the default options may not necessarily match with how you want the generated code to work in your particular project.
Having had a few years’ experience of using NSwag to generate code, I started to dig deeper into how to get the full customisation I have been used to from using the “full” NSwag experience but within the more friendly build experience of using the OpenApiReference project element.
One Gotcha To Be Aware Of!
If you use the Connected Services dialog in Visual Studio to create the connected service, you will hit a problem if you have used a Directory.Packages.props file to manage your NuGet packages centrally across your solution. The Connnected Services wizard (as at time of writing) tries to specific versions of NuGet packages.
This is part of a wider problem in Visual Studio (as at time of writing) where the NuGet Package Manager interaction clashes with the restrictions applied in Directory.Packages.props. However, this may be addressed in future versions as of the NuGet tooling and Visual Studio per this Wiki post.
If you are not familiar with using Directory.Packages.props, have a look at this blog post from Stuart Lang
Manually Updating the OpenApiReference Entry in your Project
There isn’t much documentation around on how to make adjustments to the OpenApiReference element that gets added to your csproj file, so hopefully this post will fill in some of the gaps until documentation is added to the Microsoft Docs site.
I have based this part of the post on looking through the source code at https://github.com/dotnet/aspnetcore/tree/main/src/Tools/Extensions.ApiDescription.Client and therefore some of my conclusions may be wrong, so proceed with caution if making changes to your project.
The main source of information is the Microsoft.Extensions.ApiDescription.Client.props file which defines the XML schema and includes comments that I have used here.
The OpenApiReference and OpenApiProjectReference Elements
These two elements can be added one or multiple times within an ItemGroup in your csproj file.
The main focus of this section is the OpenApiReference element that adds code generation to the current project for a specific OpenApi JSON definition.
The OpenApiProjectReference allows external project references to be added as well. More on this below,
The following attributes and sub-elements are the main areas of interest within the OpenApiReference element.
The props file makes references to other properties that live outside of the element that you can override within your csproj file.
As I haven’t used the TypeScript generator, I have focussed my commentary on the NSwagCSharp code generator.
Include Attribute (Required)
The contents of the Include attribute will depend on which element you are in.
For OpenApiReference this will be the path to the OpenApi/Swagger json file that will be the source the code generator will use.
For OpenApiProjectReference this will be the path to another project that is being referenced.
ClassName Element (Optional)
This is the name to give the class that will be generated. If not specified, the class will default to the name given in the OutputPath parameter (see below)
CodeGenerator Element (Required)
The default value is ‘NSwagCSharp’. This points to the NSwag C# client generator, more details of which below.
At time of writing, only C# and TypeScript are supported, and the value here must end with either “CSharp” or “TypeScript”. Builds will invoke a MSBuild target named “Generate(CodeGenerator)” to do actual code generation. More on this below.
Namespace Element (Optional)
This is the namespace to assign the generated class to. If not specified, the RootNamespace entry from your project will be used to put the class within your project’s namespace. You may choose to be more specific with the NSwag specific commands below.
Options Element (Optional)
These are the customisation instructions that will be passed to the code generator as command line options. See Customising The Generated Code with NSwag Commands below for details about usage with the NSwagCSharp generator
One of the problems I have been having with this element is that the contents are passed to the command line of the NSwagCSharp as-is and therefore you cannot include line breaks to make it more readable.
It would be nice if there was a new element that allows each command option to be listed as an XML sub-element in its own right that the MSBuild target concatenates and parses into the single command line to make editing the csproj file a bit easier.
This is the path to place generated code into. It is up to the code generator as to whether to interpret the path as a filename or as a directory.
The Default filename or folder name is %(Filename)Client.[cs|ts].
Filenames and relative paths (if explicitly set) are combined with
$(OpenApiCodeDirectory). Final value is likely to be a path relative to
the client project.
GlobalPropertiesToRemove (OpenApiProjectReference Only – Optional)
This is a semicolon-separated list of global properties to remove in a ProjectReference item created for the OpenApiProjectReference. These properties, along with Configuration, Platform, RuntimeIdentifier and
TargetFrameworks, are also removed when invoking the ‘OpenApiGetDocuments’ target in the referenced project.
Other Property Elements
In the section above, there are references to other properties that get set within the props file.
The properties can be overridden within your csproj file, so for completeness, I have added some commentary here
The Options element above if not populated defaults to the contents of this element, which in of itself is empty by default.
As per my comment above for Options, this suffers the same problem of all command values needing to be on the same single line.
If this is set to ‘true’ (the default), code is generated for the OpenApiReference element and any OpenApiProjectReference items before the BeforeCompile target is invoked.
However, it may be that you do not want the generated called on every single build as you may have set up a CI pipeline where the target is explicitly invoked (via a command line or as a build target) as a build step before the main build. In that case, the value can be set to ‘false’
Similar to OpenApiGenerateCodeOnBuild above, but this time determines whether to generate code at design time as well as being part of a full build. This is set to true by default.
If set to ‘true’ (the default), any projects referenced in an ItemGroup containing one or many OpenApiProjectReference elements will get built before retrieving that project’s OpenAPI documents list (or generating code).
If set to ‘false’, you need to ensure the referenced projects are built before the current project within the solution or through other means (such as a build pipeline) but IDEs such as Visual Studio and Rider may get confused about the project dependency graph in this case.
This is the default folder to place the generated code into. The value is interpreted relative to the project folder, unless already an absolute path. This forms part of the default OutputPath within the OpenApiReference above and the OpenApiProjectReference items.
The default value for this is BaseIntermediateOutputPath which is set elsewhere in your csproj file or is implicitly set by the SDK.
Customising The Generated Code with NSwag Commands
Here we get to the main reason I have written this post.
There is a huge amount of customisation that you can do to craft the generated code into a shape that suits you.
The easiest way to get an understanding of the levels of customisation is to use NSwag Studio to pay around with the various customisation options and see how the options affect the generated code.
Previously when I have been using the NSwag MSBuild task, I have pointed the task to an NSwag configuration json file saved from the NSwag Studio and let the build process get on with the job of doing the code generation as a pre-build task.
However, the OpenApiReference task adds a layer of abstraction that means that just using the NSwag configuration file is not an option. Instead, you need to pass the configuration as command line parameters via the <Options> element.
This can get a bit hairy for a couple of reasons.
- Firstly, each command has to be added to one single line which can make your csproj file a bit unwieldy to view if you have a whole load of customisations that you want to make (scroll right, scroll right, scroll right again!)
- Secondly, you need to know all the NSwag commands and the associated syntax to pass these to the Options element.
Each option that you want to pass takes the form of a command line parameter which
- starts with a forward slash
- followed by the command
- then a colon and then
- the value to pass to the command
So, something like this: /ClientBaseClass:ClientBase
The format of the value depends on the value type of the command of which there are three common ones
- boolean values are set with true or false. E.g. /GenerateOptionalParameters:true
- string values are set with the string value as-is. E.g. /ClassStyle:Poco
- string arrays are comma delimited lists of string values. E.g.
The following table is a GitHub gist copy from the GitHub repository I have set up for this and which I plan to update over time as I get a better understanding of each command and its effect on the generated code.
At time of writing, many of the descriptions have been lifted from the XML comments in the code from the NSwag repository on GitHub.
(Apologies the format of the imported markdown here is not great. I hope to make this a bit better later when I can find the time. You may want to go direct to the gist directly)
The new tooling makes the code generation build process itself a lot simpler, but there are a few hoops to jump through to customise the code generated.
I’ve been very impressed with the tooling and I look forward to seeing how to it progresses in the future.
I hope that this blog is of help to anyone else who wants to understand more about the customisation of the OpenApiReference tooling and plugs a gap in the lack of documentation currently available.