Build Better ASP.NET Core Apps with OpenAPI Generator

Table of Contents

1. Introduction
2. Prerequisites
3. Cloning the Bootstrapping Project
4. Running the Docker Compose File
5. Understanding the Open API Specification File
6. Generating the ASP.NET Core Project
7. Implementing Business Logic
8. Ignoring Generated Files in Version Control
9. Creating an Implementation Folder
10. Running the Application

Introduction

In this article, we will learn how to bootstrap an ASP.NET Core application using Open API Generator. The Open API Generator simplifies the process of creating contract-first API development with ASP.NET Core. We will explore the step-by-step process of using the Open API Generator to generate an ASP.NET Core project based on an Open API specification file.

Prerequisites

Before we begin, make sure you have the following prerequisites installed:

• Prerequisite 1
• Prerequisite 2
• Prerequisite 3

2. Cloning the Bootstrapping Project

To get started, we need to clone the bootstrapping project. This project is designed to be reusable for any contract-first API development with ASP.NET Core. You can swap out the API spec file and customize the settings as needed. Use the following command to clone the project recursively, as it also pulls in a sub-module with customized templates:

git clone --recursive [repository-url]

3. Running the Docker Compose File

Inside the cloned directory, you will find a Docker Compose file. This file allows you to run the entire application locally in containers. Open a terminal or command prompt, navigate to the cloned directory, and run the following command:

docker-compose up

This will start the application and its dependencies in Docker containers.

4. Understanding the Open API Specification File

The Open API specification file defines the paths, methods, and response types for our API. It describes the different HTTP verbs, data types, and other details required for our API development. You can customize the specification file to match your specific API requirements.

5. Generating the ASP.NET Core Project

Using the Open API specification file, we can generate a new ASP.NET Core project. After running the generate script, you will find a complete ASP.NET project in the source directory. This project includes the models defined in the API specification and stubs for the controllers. We will implement the business logic for these controllers in the next steps.

6. Implementing Business Logic

The generated project provides controller stubs that need to be implemented with our own business logic. Inside the source directory, create a new folder called "controllers/input". This folder will hold our implementation code that will not be ignored by version control.

To implement the controller logic, create a new file called "default-api-controller-input.cs" inside the "controllers/input" folder. Ensure that the file's namespace matches the existing namespace. Extend the "default-api-controller" class and implement the abstract methods.

7. Ignoring Generated Files in Version Control

To prevent accidentally committing generated code to version control, it is important to include the generated files in the .gitignore file. Update the .gitignore file in the "source/redhat.dot-to-do-list" directory to include all the generated files that should be ignored.

However, some files like "startup.cs", "program.cs", and "appsettings.json" still need to be modified. To prevent overwriting these files during future runs of the generate script, you can create an ignore file when generating the project. Specify the files to ignore, such as "program.cs", "startup.cs", and "appsettings.json".

8. Creating an Implementation Folder

To facilitate version control and separate the generated code from our implementation, create a new folder called "implementation". This folder will store the implementation code for our controllers. Unlike the "controllers/input" folder, the files in this folder will not be ignored by version control.

9. Running the Application

With the implementation in place, you can now run the application. Start the application by executing the following command:

dotnet run

After the application starts successfully, you can access the API endpoints and interact with them using Swagger documentation.

Highlights

• Bootstrap an ASP.NET Core application using Open API Generator
• Generate an ASP.NET Core project based on an Open API specification file
• Implement business logic for controllers
• Ignore generated files in version control
• Separate generated code from the implementation code in different folders

FAQ

Q: Can I use different versions of ASP.NET Core with Open API Generator? A: Yes, Open API Generator supports different versions of ASP.NET Core. Make sure to update the dependencies and configuration files accordingly.

Q: How can I customize the generated code from Open API Generator? A: You can customize the generated code by modifying the templates used by Open API Generator. These templates can be found in the customized templates folder in the bootstrapping project. Refer to the Open API Generator documentation for more details.

Q: Can I generate multiple ASP.NET Core projects from a single Open API specification file? A: Yes, you can generate multiple ASP.NET Core projects by running the generate script multiple times with different configurations and output directories.

Q: Is it recommended to contribute the generated code to version control? A: No, it is not recommended to contribute the generated code to version control. The generated code should be considered ephemeral and regenerated as needed.

Q: Can I deploy the generated ASP.NET Core project to different Kubernetes services? A: Yes, the generated ASP.NET Core project can be deployed to any Kubernetes service. Use the provided Helm chart to deploy the application to OpenShift or customize it for other Kubernetes services.

Q: What happens if I modify the generated code and run the generate script again? A: If you modify the generated code and run the generate script again, the modifications will be overwritten. It is important to keep a separate folder for your implementation code to avoid losing your changes.

Q: Can I use Visual Studio instead of Visual Studio Code for this process? A: Yes, you can use either Visual Studio or Visual Studio Code for this process. The steps may vary slightly, but the overall approach remains the same.

Q: Is it possible to update the Open API specification file and regenerate the ASP.NET Core project? A: Yes, you can update the Open API specification file and regenerate the ASP.NET Core project by running the generate script again with the updated specification file.

Q: How can I test the API endpoints after running the application? A: You can test the API endpoints by using the Swagger documentation provided by the Open API Generator. It allows you to execute the API endpoints and view the responses.

Q: Will the customized templates become unnecessary in the future? A: The author is working on contributing the customized templates back to the Open API Generator project. In the future, these templates may not be necessary as improvements are made to the default templates.

Q: What if I encounter errors or issues during the bootstrap process? A: If you encounter any errors or issues during the bootstrap process, make sure you have followed all the steps correctly and have the necessary prerequisites installed. Refer to the documentation and seek help from the community if needed.