Generating API Document In Nancy Using Swagger

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.

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.

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.

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