C Sharp

C Sharp - API topic - Swagger

Open API is a specification for describing, producing, consuming, and visualizing RESTful web services. Years ago Open API was called Swagger. Maybe Swagger started getting popular and renamed part of it’s technologies to Open API.

Swagger is a tool that helps you document your API’s.

You would add different different stuff to your methods to document your API’s.

Here’s an example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/// <summary>
/// Returns a ReconcileViewModel object (specifically the one with the ID provided)
/// </summary>
/// <param name="id">
/// This is the ID of the Reconcile record you are looking for. 
/// Maps to Reconiles.Id </param>
/// <returns></returns>
[SwaggerResponse(
    StatusCodes.Status200OK,
    "HTTP 200 means a model is being returned. Check the WasSuccessfulTrue to determine if it worked properly",
    typeof(IResult<ReconcileViewModel>))]
[SwaggerResponseExample(
    StatusCodes.Status200OK,
    typeof(ReconcilesControllerSwashbuckleExamples.ReconcileGetOneExample))]
[SwaggerResponseExample(
    StatusCodes.Status200OK,
    typeof(ReconcilesControllerSwashbuckleExamples.ReconcileGetAll))]
[HttpGet("{id}")]
public async Task<IActionResult> GetOne(long id)
{
    var result = await _reconcileService.GetReconcileById(id);
    return Ok(result);
}

You’ll notice a mix of comments (that start with ///) and Annotations. The compiler will call a function to read through the code and generate documentation. In this case the documentation that is generated will give you a summary and a description of the ID parameter. There is also comments that describe what is returned.

More information about Swagger can be found here:

  • Swashbuckle There are articles in this section that describe different aspects of Swashbuckle.