In this post, I will explain how to utilize OpenAPI Generator tool to auto-generate the ASP.NET Core Web API controllers and models from an OpenAPI YAML specification.

Generate ASP.NET Core controllers and models

Let’s take petstore.yaml as an example. To generate ASP.NET Core Web API, I will run OpenAPI Generator commands via Docker on my Windows 10 machine.

docker run --rm ^
-v /C/Users/fiona/Petstore:/local openapitools/openapi-generator-cli generate ^
-i /local/petstore.yaml ^
-g aspnetcore ^
-c /local/config.json ^
-o /local/server

Firstly, I created a directory “C:\Users\fiona\Petstore”, copied petstore.yaml into it. Then I mounted my Windows directory “C:\Users\fiona\Petstore” to directory “/local” in the container. The Docker image “openapitools/openapi-generator-cli” comes from https://hub.docker.com/r/openapitools/openapi-generator-cli.

-v /C/Users/fiona/Petstore:/local openapitools/openapi-generator-cli generate

Because “C:\Users\fiona\Petstore” is mapped to “/local” in the container, I pointed to the yaml file using “/local/petstore.yaml”.

-i /local/petstore.yaml

OpenAPI Generator is able to generate all kinds of clients and servers. Please refer to Generators List to learn more.

-g aspnetcore

Please refer to ASP.NET Core Config Options to see what options you can config.

-c /local/config.json

An example of configuration options are as below:

{
  "packageName": "Petstore.API",
  "packageTitle": "Pet Store",
  "aspnetCoreVersion": "6.0",
  "enumNameSuffix": "",
  "enumValueSuffix": "",
  "operationIsAsync": true,
  "operationResultTask": true
}

Finally we specify the output directory.

-o /local/server

Customize Templates

From time to time, we may want to tweak the templates a little bit. For example, we noticed that the generated Async methods are not named with Async suffix. To fix it, what we can do is:

Firstly, we downloaded the controller template controller.mustache. You might be new to Mustache templates. I think the best resource to quickly wrap it up is the Mustache Manual.

Next we copied the Mustache template to a directory named “templates” under “C:\Users\fiona\Petstore”.

Finally, we modified the template, adding “Async” suffix to the method name when the method is async.

tempate

To use the customized templates in the generator, please add:

-t /local/templates