mdabbagh88 / fubumvc-swagger

FubuMVC convention for creating API documentation for your content negotiation enabled actions

FubuMVC Swagger

This project helps your FubuMVC web application generate API documentation via Swagger.

See our Hello Swagger live demo.

How do I get it?

We have a nuget package available.

PM> Install-Package FubuMVC.Swagger

Building Swagger

To build just run rake grabbing the albacore gem if you don't already have it.

gem install albacore
rake

How do I put this in my peanut butter?

Note: This should all be simplified when I find the time to figure out Fubu Bottles.

Your API documented should support content negitiation and be grouped under the route /api. Take a look at the HelloSwagger for examples.

Checklist

Add a reference to this project. Why not use nuget!

Add the following to your FubuRegistry:

ApplyConvention<SwaggerConvention>();
Services(s=> s.AddService<IActionGrouper, APIRouteGrouper>());

Copy the swagger-ui directory into your /content direcotry.

Launch your web app and take a look at the /api to see if it is working.

What does this convention do?

Three routes will be added to your application:

GET /api

This route serves up the Swagger-UI page currently embedded into FubuSwagger. This part needs work.

GET /api/resources.json

Swagger UI does some resource discovery and uses the output of this route to find all of the API groups in your project.

GET /api/{GroupKey}.json

Details of each API group present in your app.

Pointing a Swagger UI web site at http://localhost:port/api/ should render pretty API documentation for your web application.

Why do I not see documentation for my actions?

Make sure the actions you wish to document are enabled for "Conneg"

In this example I have two marker interfaces which are used to mark input models on actions which will be APIs.

graph.Behaviors
 .Where(x => x.InputType().CanBeCastTo<IApi>() || x.InputType().CanBeCastTo<IUnauthenticatedApi>())
 .Each(x => x.MakeAsymmetricJson());

This example will force the result of these actions to be JSON. Note: This configuration is working around a bug in FubuMVC where normal browser usage will return XML for Conneg enabled endpoints. :(

Better yet take a look at the HelloSwagger demo application and see how it is wired up and organized.

How do I add more detail to my APIs

You can use data annotations to mark up your input models and their properties.

[Description("Workflow object history")]
public class HistoryRequest : IApi 
{
    [Required, Description("Type of workflow object. Typically this is 'case'.")]
    [AllowableValues("case", "subcase", "solution", "<any workflow object name>")]
    public string Type { get; set; }
    [Required, Description("Id of the workflow object.")]
    public string Id { get; set; }

    [Description("Limit the amout of history returned the given number of days. When this parameter is not specified. All history items will be returned.")]
	public int DaysOfHistory { get; set; }
}