Nancy.Metadata.Swagger.Core

This is a port of the existing Nancy.Metadata.Swagger repository but updated to target the latest version of NancyFx and also targeting NetStandard 2.0. Most of the modifications have been minor tweaks and havent really affected the surface of the API in order to maintain backwards compatibility when targeting Nancy 1.+ and 2.+.

Note: Since Nancyfx is no longer being maintained i will be deprioritizing this library, please check here for details

Introduction

Nancy.Metadata.Swagger is a library that makes it easier to create API documentation for swagger 2.0 with Nancy metadata modules. This targets exclusively the 2.0 Swagger specification. For an updated version that targets OpenApi 3.0.0, check the following library.

Dependencies

Nancy.Metadata.Swagger uses Newtonsoft Json.Net and NJsonSchema for .Net to generate the object schema structure. Also it uses some of Nancy libraries, so those will be installed as well as part of the dependencies.

Gettings started

Install Nancy.Metadata.Swagger.Core via nuget packages:

PM> Install-Package Nancy.Metadata.Swagger.Core

You will also need the Nancy.Metadata.Modules package from nuget:

PM> Install-Package Nancy.Metadata.Modules

Once this is done, locate your module implementations and generate a MetadataModule with the descriptions.

This is a sample implementation of a Nancy Module:

public class RootModule : NancyModule
{
    public RootModule() : base("/api")
    {
        Get["SimpleRequestWithParameter", "/hello/{name}"] = r => Hello(r.name);
    }
}

The example metadata module (for %modulename%Module should be named %modulename%MetadataModule):

public class RootMetadataModule : MetadataModule<SwaggerRouteMetadata>
{
    public RootMetadataModule()
    {
        Describe["SimpleRequestWithParameter"] = desc => new SwaggerRouteMetadata(desc)
            .With(i => i.WithResponseModel("200", typeof(SimpleResponseModel), "Sample response")
                        .WithRequestParameter("name"));
    }
}

** !IMPORTANT: Metadata module class should be placed at the same namespace within the module for discovering purposes**

After doing this for each module desired, configure the endpoint that will serve the documents described.

Adding the docs module

This module will return your json documentation. The key is the inheritance from SwaggerDocsModuleBase.

Here's a sample module:

public class DocsModule : SwaggerDocsModuleBase
{
    public DocsModule(IRouteCacheProvider routeCacheProvider)
        : base(routeCacheProvider,
          "/api/docs",                   // where module should be located
          "Sample API documentation",    // title
          "v1.0",                        // api version
          "localhost:5000",              // host
          "/api",                        // api base url (ie /dev, /api)
          "http")                        // schemes
    {
    }
}

Default values are provided, but it is encouraged that you configure your own values, obtaining them from config files or environment vars (see the sample).

Adding swagger UI

This is completely optional and its mostly for discovery purposes. It is feasible to add Swagger-UI (you can download it from swagger-ui or check the github repository here or heck, use npm) and point it to your document module. At the index.html file you can set the default url where swagger-ui should get the json documentation file. For more details check the sample application.

Missing Swagger features

Since Swagger's latest standard is for OpenApi (Version 3.+), i would not be putting any type of effort into adding enhancements to this library, since the functionality mostly covers my current needs. I will take care of bumps to the release version of netcore for Nancy, Swagger-UI and any bugs found. By all means, Feel free to Clone and PR away if you would like to add any new features.

Jaxelr / Nancy.Metadata.Swagger.Core