Learn and Understand NSwag Document Generation — Simple use case
Welcome back buddy! If you are in this article then you should have already went through my article 1 on NSwag. If not please check it out before moving forward as we will be building upon from where we left. So, lets get started.
Use Case: Modify the Open API Specification document Name and version.
Hello buddy! before we start coding. Let me first explain what we are going to do in this use case. This is another simple use case where either your work or personal reason demanded to change the default name of the Open API Spec document created and hosted in the previous exercise. As you know default names doesn’t give the consumers the right amount of confidence and indicates that the swagger document is not being maintained upto date and attracts less consumers to our powerful APIs. So, lets change that perspective together.
- Navigate to the program.cs inside the project we created and find the method called builder.Services.AddOpenApiDocument();
- Lets change the method a bit, instead of using the method without parameters. Lets use the below method overload from NSwag nuget, which will allow us to change some default NSwag document generation settings.
builder.Services.AddOpenApiDocument((document, serviceProvider) => { });3. The above method takes an Action with two parameters AspNetCoreOpenApiDocumentGeneratorSettings settings, IServiceProvider services as shown in the below image taken from the nuget library directly.
AspNetCoreOpenApiDocumentGeneratorSettings: A settings class with different properties, which we look through out this article and upcoming articles as we are going to change the default values of these properties and watch the required changes taking effect.
IServiceProvider: This will help us to inject some extra services into the document generation process for some of the advanced use cases. Which we will learn together as well. But for the current article we will just work with the paramerter 1 to change the default settings.
4. Now let change our AddOpenApiDocument method as below to change the default document name (version).
builder.Services.AddOpenApiDocument((document, serviceProvider) =>
{
document.DocumentName = "v1";
});This change will rename the default version or name of the document to “v1”. Look at the below screenshots to understand the before and after changes.
If you observe the default document name “v1” in the picture has been changed to “development_v1” which is more intuitive, giving the consumer an idea that this a development envrionment version 1 swagger document.
This is all good but if you examine our Swagger UI. Its still shows a very weird default title “My Title” I don’t like it. Let change it to a more meaningful name.
5. Now lets change the AddOpenApiDocument method as shown below.
builder.Services.AddOpenApiDocument((document, serviceProvider) =>
{
document.DocumentName = "development_v1";
document.PostProcess = d => d.Info.Title = "Arcade APIs - Development";
});Lets understand what we have did. In the above code snippet we have updated PostProcess of AspNetCoreOpenApiDocumentGeneratorSettings which is an another action taking OpenApiDocument class which has a object property “Info” of type OpenApiInfo. This OpenApiInfo class has the property called Title which is what we need to change to apply a different title for our swagger document.
6. Now lets run and verify the change on our Swagger UI.
Now the title of our application looks much interesting to the consumer.
Conclusion:
Yahhh! 😃 we have successfully learned how to customize the document name and title of our Open API spec document both as a JSON format as well as on Swagger UI. Making our application more interesting for our consumers. In the next chapter lets learn about how to customize and host swagger ui and swagger JSON document to a different route within our application. Look for the link to the next article!
Before I forget here is Github Repository Url for the current exercise. See ya in the next one!!!
