Generating API documentation

[mat-mcloughlin]

Just opening up an issue so we can discuss the possibility of having Nancy generate documentation for the applications built using it.

As an example of how this is done in our beloved Web API see here http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

[jchannon]

We already have documentation on routes via having a corresponding resx file for each module. However what I would like is some way of doing this and producing something like Swagger from the information we provide about the routes. http://swagger.wordnik.com/#!/pet

[thecodejunkie]

Posting this from my comments on JabbR

We provide an interface

public interface IRouteMetaDataProvider
{
    object Get(string url);
}

That is called when Nancy builds the route cache. When the cache is built, Nancy creates a [RouteDescription](https://github.com/NancyFx/Nancy/blob/master/src/Nancy/Routing/RouteDescription.cs
public class DefaultRouteMetaDataProvider) instance for reach route. So we extend that class to contain a Metadata property of type object. The reason it's an object is because it's format agnostic. I don't care what metadata you want to store and how you want to use it

    public object Get(string url)
    {
        // 1 use url to get all data you want
        // 2 stick it into a DTO that fills your requirements
        // return it
    }
}

Then when it comes to presenting the information you do the following, you create a NancyModule that takes a dependency on RouteCacheProvider and from there on you have access to all the RouteDescription instances and can do whatever you want (render views, return plain objects and have conneg dictate the format etc).

We could ship a default implementation of the IRouteMetaDataProvider interface and a default implementation of a NancyModule that exposes the data in some way and give you the option to override them with your own implementations. This keeps it inline with the super-duper-happy-path

TL;DR

1. I don't care where you get the info
2. I don't care about your format or what you store
3. I don't care how you expose it

All I do it give you the tools to associate METADATA with a given route
Ship it!

Thoughts?

[thecodejunkie]

So, I spiked this out in 20 minutes and created a very simple IRouteMetadataProvider implementation. The interface was defines as

    public interface IRouteMetadataProvider
    {
        object GetMetadata(RouteDescription routeDescription);
    }

And my basic implementation was

    public class DefaultRouteMetadataProvider : IRouteMetadataProvider
    {
        public object GetMetadata(RouteDescription routeDescription)
        {
            return new MyRouteMetadata();
        }
    }

The MyRouteMetadata class is a custom DTO that I created to contain my application specific metadata

    public class MyRouteMetadata
    {
        public MyRouteMetadata()
        {
            this.Description = "Lorem ipsum";
            this.ValidStatusCodes = new[] { HttpStatusCode.Accepted, HttpStatusCode.OK, HttpStatusCode.Processing };
        }

        public string Description { get; set; }

        public IEnumerable<HttpStatusCode> ValidStatusCodes { get; set; }
    }

I then created a simple route, in a module that took a dependency on IRouteCacheProvider (currently in Nancy) and returned a view, passing the
cache to the view as a model

    Get["/meta"] = parameters => {
        return View["meta", routeCacheProvider.GetCache()];
    };

The meta view is a simple Razor view

    <h1>Route metadata</h1>
    <p>Below is a list of route metadata that was generated from a custom IRouteMetadataProvider implementation</p>

    <div class="meta">
        @foreach (var module in @Model)
        {
            foreach (var route in @module.Value)
            {
                var meta = (MyRouteMetadata)route.Item2.Metadata;

                <div>
                    <h1>@route.Item2.Path</h1>
                    <h3>@route.Item2.Method</h3>

                    Description:
                    <p>@meta.Description</p>

                    Valid return status codes:
                    <p>
                        @string.Join(", ", @meta.ValidStatusCodes)
                    </p>

                </div>
            }
        }
    </div>

And that produced the following view

[thecodejunkie]

As you can see I can now have a custom DTO for my metadata, meaning I can stick what ever stuff I want in there. Code samples, descriptions, return codes, error codes, urls to end points, links to samples etc..

If I'd returned a Negotiator instead then I could have requested for my metadata in any negotionable format (json, xml and view out of the box) and add more formats by implementing one or more IResponseProcessor implementations

Word of caution for negotiation. This is a very quick spike and the IRouteCache probably wouldn't serialize to json very well, so you should probably create you own model type. I could have added Path and Model to my MyRouteMetadata type and passed in an IEnumerable<MyRouteMetadata> as the model instead and it would work just fine.

[thecodejunkie]

By the way, I extended RouteDescription to have an object Metadata { get; set; } property where the metadata DTO is shoved in. It's done by the IRouteCache when it builds the cache at application startup.

I will push the code to a branch on my Nancy fork so you can play with it and see if it does what you want. Would be nice to see if we could connect it to some third party tool like Swagger as well

[thecodejunkie]

Updated it again. This time I added a CodeSample property to my MyRouteMetadata DTO and stuck a bit of code in there. I then extended my view to download highlight.js and highlight my code. This is what how turned out

Pretty sure this is the most flexible approach we can add - and yet it's so easy!

[thecodejunkie]

Don't you all comment at once ;)

[chrissie1]

I'm ok with this.

[felipeleusin]

Don't know how helpful this will be, but i've been using http://apidocjs.com/ when working with nodejs and most of my coworkers/pms really liked it. Maybe it can give some inspiration, I know there is some conceptual differences between Node and Nancy, specially because we can't really comment on the properties but still.

One thing I really like is being able to include metadata alongside route definition, I think it's going but maybe a [RouteResponse(string contentType, type response)] parameter that get's picked up...

[thecodejunkie]

You can find the code at https://github.com/thecodejunkie/Nancy/tree/route-metadata-spike
Look at the IRouteMetadataProvider interface. In the same file you will find the DefaultRouteMetadataProvider and MyRouteMetadata sample implementations.
The metadata itself it associated with the RouteDescription.Metadata property in the IRouteCache.BuildCache method (which would be in RouteCache.BuildCache for the default implementation)

[dealproc]

Interested to see how this develops. For api development, this is something that I am considering.

[thecodejunkie]

@felipeleusin I am afraid that that will never work for Nancy, unless the C# team changes how you can use attributes. A route declaration in Nancy (this is only slightly true, keep reading) is a property call (Get etc are properties that returns an item with an indexer on), and you can only put attributes on declarations, not call operations. That said, this only holds true for the default implementation of the INancyModule interface (the default implementation being the NancyModule class).

You can provide alternative implementations, such as we have done in our demo https://github.com/NancyFx/Nancy/tree/master/src/Nancy.Demo.CustomModule where we created a new base class, called the UglifiedNancyModule which base its route declarations on methods, like ASP.NET MVC/WebAPI. You could create your own, similar implementation, and have your IRouteMetadataProvider read the metadata of your method declarations.

Personally I think the inline approach is only viable for the simplest form of documentation. As soon as you want to include a bit more verbose description, return values, exceptions, code samples etc. then it's going to be very clunky to keep inline. I am more a fan of declaring these separate to my routes so I can easily manage them independently of you routes.

That said, this is just a proof-of-concept spike and we're more than willing to have alternate spikes/suggestions brought to the table so we can expose ourselves to as many scenarions as possible and get the best/most flexible implementation into Nancy

[khellang]

@thecodejunkie Just a thought; what if we kept the condition and route action delegates around as expressions instead (or in addition to the compiled delegates)? The routeExpression.ToString() could be interesting to have in the documentation.

[thecodejunkie]

@khellang I was thinking the same last night when I decided to push in the entire RouteDescription into the IRouteMetadataProvider. I wonder what kind of impact it would have on the code and performance

[jchannon]

There's only one way to find out.....Go! :)