Swagger Documentation for existing API’s

Code First. Documentation Next.

Photo courtesy: https://swagger.io/getmedia/7bd69649-e725-4342-bda0-b68b7b00bc4f/SwaggerHub-UI-Example

There are 2 approaches to building API’s both widely used - Code first and Design first. Though design first is gaining rapid popularity, there is still a lot of Code first approach API’s waiting to be documented. Let’s see how easy it is to generate swagger documentation for existing API’s.

In this article we will be working with:

1. .NET Core Web API(existing or new web API Project).
2. NSwag Nuget package for generating the swagger json
3. Import the swagger json to Swagger hub(trial version)

NSwag and Existing API

The API was built to work with an angular front end app. It has 3 controllers, Email Controller, Weather Controller and News Controller. We will be able to see all of the available API end points and how to work with it in our swagger documentation.

NSwag Nuget package:

Open the API solution using Visual Studio, and install NSwag.AspNetCore Nuget package.

Once the package in installed, add the following snippet of code in Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();
    // Register the Swagger services
    services.AddSwaggerDocument();
}
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();
    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();
    app.UseMvc();
}

That’s it, we have added the Swagger generating middleware to our app. Let’s get our middleware to work and generate the swagger and swagger.json file. Click here to learn more about NSwag capabilities. Serve the API over your local host port and you can access the swagger by navigating to:

• http://localhost:<port>/swagger to view the Swagger UI.
• http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

Local host swagger UI that shows my controllers and the api resources

Open the Swagger.json file and save it as your api swagger.json file.

swagger.json file

We need the swagger.json file to import into SwaggerHub. also to generate Open API specs for our API.

Explore SwaggerHub

Swagger Hub provides a lot of advantages and serves a single source of truth for your API development, testing and documentation. We can sign up for a free account to generate OAS. Once you sign up for a free account, it opens a hub of API’s you have imported/hosted/published. Click here to explore Swagger hub.

Lets import our swagger.json file so we can generate the API on Swagger hub and also to get OAS 3.0 yaml definition for the API.

Import the json file and hit UploadFile

This will import the file and convert the json to OAS2.0 or 3.0. You will have an opportunity to convert between the specs versions inside the hub. See below:

my-api-swagger-hub

You can also host this API to be publicly accessible, export the specs and API, publish your API to swagger hub and much much more!