Swagger specification which are also known now as OpenAPI specification, were found back in 2010 to help describe API’s in a way that it is both easy to read by humans and machines, in a simple format (JSON, YAML)

That lead to granting us a lot of power as we could do so much with this descriptions starting from documentation, creating SDKs, tests! and much more which could be auto generated using many tools, in here we are going to use Swagger to show case it.

Why do we need it?

Lets take an example and will try to fit the demo inside of it.

We are part of the development team which takes care of server side logic and API’s which mobile application or other services need to interact with.

Things are going great! as good developers we were always writing docs on each endpoint what to take and to expect from it.

These docs are then passed to any consumer of the API.

All good till now but still a bit more time consuming as we are both developing and making sure the docs are in sync.

At one point we had an urgent requirement for a change! we did a fast plan after which committed and pushed, but we forgot to update the docs!.

At this point our docs are out of sync! some of the API’s went to be a black box that only dev team knows about.

This will lead to unpleasant consumer experience and more work to find out what each endpoint requires.

Solution! 🙂

What we want to build is a system that could read our API from code and generate a documentation that accurately describes it.

This could be done with the help of swagger.

Lets add it with a couple of steps for a new Asp.net Core project (will work for an existing project too)

Run the following command in PMC (Package Manger Console)

install-pacakge Swashbuckle.AspNetCore

This will add the needed swagger packages.

In Startup.cs add the following code in ConfigureServices function

services.AddSwaggerGen();

Go to startup and add the following code in Configure function

builder.UseSwagger();

builder.UseSwaggerUI(options =>
{
    options.RoutePrefix = "swagger";
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "App v1");
});

Now we can run our project and go the endpoint (RoutePrefix) that we have set in Configure function, you should see something like that.

WOW we got our auto generated docs! but then were is the OpenAPI specification that we talked about you would ask!

Lets go and see the .Json file that this UI is reading from.

Here is the description of our API’s in a simple format which is now being used to create docs but we could use in in many more things.

You can customize a lot of things while adding swagger in your project such as adding authentication schemas, filtering data and much more.

You can see and example Here which the code for will be found on GitHub.

Hope you enjoyed the read.