OpenAPI

Redoc - a library used in ASP.Net to support OpenAPI

Open api is a standard for documenting API’s

Swashbuckle helps the developer document their API’s. So does Redoc.

If your program is properly configured. Then this will read the swagger.json file, and generate a web page for you to view instructions to the API.

When you start your API program with /redoc, it will open the redoc page, where you can view the documentation.

Here’s a simple example

Redoc Opening page

If you click the AccountTypes link. The navigation section will and showing you the interface associated with that part of the API.

Here’s an example.

Redoc Starting to Navigate

The interface provides 3 panes, the first is navigation. The second is documentation, and the third shows samples.

For comparison here’s what the Swagger interface looks like.

Swagger Opening page

Each row on the interface is a method. You can click on the method to get more information. Her eis an example of /api/v1/AccountTypes

Swagger Information about Get AccountTypes

Comparison of Swagger and Redoc

  • Redoc is a bit more readable.
  • Redoc says you can design the output better.
  • Swagger will allow you to execute those methods. Redoc does not.

For me the Redoc interface is more readable. I will probably stick to Swagger for now. But I will integrate both into my project.

Adding Redoc to your project

If you have already added Swashbuckle to your project, then this will be simple.

Use Nuget to install the following Library:

  • Swashbuckle.AspNetCore.Redoc

After the swagger library is installed, you will need to add the following to your program.cs

1
2
3
4
5
6
7
8
9
app.UseReDoc(c => {
    c.DocumentTitle = "GL API Documentation";
    c.SpecUrl = "/swagger/v1/swagger.json";
    c.RequiredPropsFirst();
    c.NoAutoAuth();
    c.HideDownloadButton();
    c.HideHostname();
    c.RoutePrefix = "redoc";
});

At this point you can start your program and go to /redoc to view the documentation - redoc style.

Here is what my AccountTypes method looks like in code. 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// ====================================================================================================
// getAllAsync -- returns a collection of accountType objects
// ====================================================================================================
/// <summary>
/// Retrieves a list of accountType records added to the database.
/// </summary>
/// <returns>
/// Returns a List of AccountTypeViewModel objects
/// </returns>
/// <remarks>
/// Sample response:
/// ```json
/// {
///     "model": [
///         {
///             "description": "Test",
///             "typeCode": "Test",
///             "typeName": "Test"
///         },
///         {
///             "description": "Test 2",
///             "typeCode": "Test 2",
///             "typeName": "Test 2"
///         }
///     ],
///     "wasSuccessful": true,
///     "message": {
///         "correlationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
///         "friendlyMessage": "Retrieved all AccountType records successfully",
///         "detailedMessage": "Retrieved all AccountType records successfully",
///         "level": "Info"
///     }
/// }
/// ```
/// </remarks>        /// <example>
/// https://localhost:7230/api/v1/accountTypes
/// </example>
/// <response code="200">AccountType list retrieved</response>
/// <response code="404">AccountType not found</response>
/// <response code="500">Oops! Can't lookup your AccountType right now</response>
[ProducesResponseType(typeof(List<AccountTypeVM>), 200)]
[ProducesResponseType(404)]
[ProducesResponseType(500)]
[HttpGet]
public async Task<IActionResult> GetAllAsync()
{
    IResult <List<AccountTypeVM>> result = await _accountTypeService.GetAllAccountTypesAsync();
    return Ok(result);
}

The code startign with 2 slashes helps me separate the methods from one another. My eyes cannot read the code if it is all together.

[HttpGet] is used to indicate that this is a GET method.

The rest of the code is the documentation used by both Swagger and Redoc.

Experience

I’m fairly new to OpenAPI. In the past I have used the following libraries.

  • Swashbuckle.AspNetCore
  • Swashbuckle.AspNetCore.Annotations - Used if you are adding swashbuckle based annotations
  • Swashbuckle.AspNetCore.Filters - Used if you are adding examples to the swagger output. (Largely Obsolete)

So adding Redoc was easy, I just added Swashbuckle.AspNetCore.Redoc and added the code to my program.cs.

The first time I ran the API, it worked. But when I tried the /redoc page, I was receiving out of memory errors.

After a bit of studying I discovered that the Swashbuckle.AspNetCore.Filters library was largely obsolete. I had to resort to AI to help me find a solution to the Out of Memory error. The solution was to remove the code used to drive the Swashbuckle.AspNetCore.Filters library. and the UseReDoc arguments.

References