Generating API Document In Nancy Using Swagger

Introduction

In my last article, "Generating API Document In Nancy," I introduced how to generate an easy API document in Nancy without third party plugins, which contain less information. Today, we will learn how to use Swagger to generate a richer API document in Nancy through an open source project, Nancy.Swagger.

What is Swagger?

Swagger is a powerful open source framework backed by a large ecosystem of tools that helps you design, build, document, and consume your RESTful APIs.

We can use JSON and YAML to finish it. JSON seems more convenient when we are coding, because we can use lots of JSON libraries in our projects. By the way, the syntax of YAML is also easy to understand!

How does Swagger work? We only need to provide some data to Swagger and it will render the document view which we can see. And, Nancy.Swagger plays a vital role in providing data!

Now, let's begin.

Step 1

This is a previous step of this article. We need to do some preparation.

1. Create a new empty solution named ApiApp, add three projects to the solution

• Web - contains the swagger-ui and other static files
• Modules - contain all Nancy modules and metadata modules
• Models - contains all the models

2. Download the static files of Swagger and add them to the ApiApp project. And I made them Embedded Resource which can be output to the bin directory.
   
   
   

3. Add a Bootstrapper class and enable the static files of Swagger in the method ConfigureConventions.
   
   1. public class Bootstrapper : DefaultNancyBootstrapper
   2. {
   3. protected override void ConfigureConventions(NancyConventions nancyConventions)
   4. {
   5. base.ConfigureConventions(nancyConventions);
   6. nancyConventions.StaticContentsConventions.Add(StaticContentConventionBuilder.AddDirectory("swagger-ui"));
   7. }
   8. }

4. Create a new doc.html file, which will show us the API document. We need to copy the content from the downloaded index.html in swagger-ui to the doc.html.

5. Add a HomeModule class to deal with the first time the document is opened. When we open our index page of our API, we will be redirected to the document page.
   
   1. public class HomeModule : NancyModule
   2. {
   3. public HomeModule()
   4. {
   5. Get("/", _ =>
   6. {
   7. return Response.AsRedirect("/swagger-ui");
   8. });
   10. Get("/swagger-ui",_=>
   11. {
   12. var url = $"{Request.Url.BasePath}/api-docs";
   13. return View["doc", url];
   14. });
   15. }
   16. }

6. Edit the JavaScript code of doc.html so that we can get our own API information.
   
   1. window.onload = function() {
   2. // Build a system
   3. const ui = SwaggerUIBundle({
   4. url: "@Model", //replace the default url to our demo's url
   5. dom_id: '#swagger-ui',
   6. presets: [
   7. SwaggerUIBundle.presets.apis,
   8. SwaggerUIStandalonePreset
   9. ],
   10. plugins: [
   11. SwaggerUIBundle.plugins.DownloadUrl
   12. ],
   13. layout: "StandaloneLayout"})
   14. window.ui = ui;
   15. }

So far, we have finished the previous work of our demo.

Note

Nancy.Swagger does not include the swagger-ui, which is different compared to Swashbuckle.AspNetCore, which we use in ASP.NET Core Web API. Thus, we need to add the swagger-ui by ourselves.

Step 2

Create a new module class named ProductsModule. This module contains all APIs.

Step 3

Before writing code on a metadata module, we need to add the header for Swagger. It's part of our document, which is basic on OpenAPI Specification. You can follow this link.

Open our Bootrstapper class and add the code given below.

This code specifies the header information of our API document. After you run the code (not now!), you may see the screenshot.

Step 4

In this step, we will create a metadata module to describe our API.

I added some annotations on the code given above to show what they mean. For more details about them, you can visit the wiki page of Nancy.Swagger.

Now, we can run the project.

Here are some screenshots of the result

Screenshot 1

Screenshot 1 is the overview of our API document. We can find out there are two groups in our document, HTTP method of APIs, descriptions of APIs etc.

Screenshot 2

Screenshot 2 is the default view of the API GetProdcutList. We can find out the information, which we described in metadata module.

Screenshot 3

Screenshot 3 is the executed view of the API GetProdcutList. We can find out the information, which is the Server response, such as the status code and the response body.There is a CURL command, which you can find as well. When we use the terminal, we can get the same result from this request.

Note

There is a problem to which we need to pay attention. The file path between Modules and MetadataModules.

Path of Modules	Path of MetadataModules
./ProductsModule	./ProductsMetadataModule
./ProductsModule	./Metadata/ProductsMetadataModule
./Modules/ProductsModule	./Metadata/ProductsMetadataModule

When we create the modules, we need to observe about the rules, otherwise you can not get the route information in Nancy.

Be aware of the name of our Module and the MetadataModule. For example, I already have a module named ProductsModule and I want to create a MetadataModule of this module. What should I name it? ProductMetadataModule? ProductsMetadataModule? Or others? Maybe, there is only one answer: ProductsMetadataModule! Because there are some restrictions.

We can find out the reason on DefaultMetadataModuleConventions class in the project Nancy.Metadata.Modules

Summary

Swagger makes our API document beautiful and executable, and reduces our time to write the documents.

A mind map is given below to show the information about this article.

Thanks for your patient reading.