Nancy.Metadata.OpenApi

This library extends Nancy modules in order to produce a specification file that will follow the OpenAPI spec.

You can find the latest specifications of OpenAPI here

This library targets Nancy 2.0, for previous versions that target Nancy 1.X check release that target version 0.7.0 and below.

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

Builds

Appveyor	Branch	Coverage
	master
	develop

Packages

NuGet (Stable)	MyGet (Prerelease)

Installation

Via nuget:

PM> Install-Package Nancy.Metadata.OpenApi

You also need the Metadata library provided by Nancyfx:

PM> Install-Package Nancy.Metadata.Modules

Usage

Define a docs module that will serve our OpenApi Json (currently only json is supported) document:

using Nancy.Metadata.OpenApi.Model;
using Nancy.Metadata.OpenApi.Modules;

public class DocsModule : OpenApiDocsModuleBase //We must inherit from the OpenApiDocsModuleBase
{
    //Could be an array of Servers corresponding to different environments. 
    public static Server Server
        => new Server() { Description = "My Descripton", Url = "http://localhost:5000/" };

    public static string[] Tags => new string[] { "sample", "openapi" };

    public DocsModule(IRouteCacheProvider routeCacheProvider) :
        base(routeCacheProvider,
        "/api/docs/openapi.json",       //Document location path
        "My API ",                      //Api Title 
        "v1.0",                         //Version of the Api
        Server,
        "/api",                         //Base url
        Tags)                           //Document Tags
    {
    }
}

We could optionally, if the information is needed, add Contact, License and External Docs information:

public class DocsModule : OpenApiDocsModuleBase //We must inherit from the OpenApiDocsModuleBase
{
    public static Server Server
        => new Server() { Description = "My Descripton", Url = "http://localhost:5001/" };

    public static string[] Tags => new string[] { "sample", "openapi" };

    public DocsModule(IRouteCacheProvider routeCacheProvider) :
        base(routeCacheProvider, "/api/docs/openapi.json", "My API 2", "v1.1", Server, "/api", Tags)
    {
        //Optional information.
        WithContact("Contact Information", "jaxelrojas@email.com", "https://jaxelr.github.io");

        //Optional information.
        WithLicense("MIT", "https://opensource.org/licenses/MIT");

        //Optional Information.
        WithExternalDocument("This is a tutorial or a spec doc.", "https://jaxelr.github.io")
    }
}

Then, define the Nancy modules as you would usually do:

//Example using Nancy v2
public class MyModule : NancyModule
{
    public MyModule() : base("/api")
    {
        Get("/hello", r => HelloWorld(), name: "SimpleRequest");
        Get("/hello/{name}", r => Hello(r.name), name: "SimpleRequestWithParameter");
    }
}

//Skipped method implementations for brevity sake...

Finally, you must define the metadata of the operations. To do so, simply declare the metadata module (using Nancy.Metadata.Modules) on the same namespace as the endpoint operations were defined, using the inherited MetadataModule class and the OpenApiRouteMetadata class defined on Nancy.Metadata.OpenApi.Core.

using Nancy.Metadata.Modules;
using Nancy.Metadata.OpenApi.Core;
using Nancy.Metadata.OpenApi.Fluent;

public class MyMetadataModule : MetadataModule<OpenApiRouteMetadata>
{
    public MyMetadataModule()
    {
        Describe["SimpleRequest"] = desc => new OpenApiRouteMetadata(desc)
            .With(i => i.WithResponseModel("200", typeof(SimpleResponseModel), "Sample response")
                        .WithSummary("Simple GET example"));

        Describe["SimpleRequestWithParameter"] = desc => new OpenApiRouteMetadata(desc)
            .With(i => i.WithResponseModel("200", typeof(SimpleResponseModel), "Sample response")
                        .WithRequestParameter("name")
                        .WithSummary("Simple GET with parameters"));
    }
}

Thats pretty much it, the docs endpoint defined above would generate some valid OpenApi Json. You can validate the Open Api endpoint using swagger-ui. (For those unaware, OpenApi used to be called Swagger, so any reference to Swagger usually means version <= 2.0) Check the Compatibility table of UI for usage.

For a working example, see the sample app that uses the Swagger-UI site as a validator.

Contributing

Check the guidelines for a simple explanation on how you could contribute.