Api Explorer for external project or assembly

Question

I want to use Web API's Api Explorer in order to start generating my own documentation html pages. What I'm trying to aim at is something like described here: http://blogs.msdn.com/b/yaohuang1/archive/2013/01/20/design-time-generation-of-help-page-or-proxy-for-asp-net-web-api.aspx

However, this project is a bit outdated and does not work with the current web api. I want to have:

1. A console program that has api explorer core libraries installed in it.
2. It takes in an assembly from another project and runs Api explorer on it to get all the REST paths and methods.
3. I don't want Api explorer or the help pages to be installed on the project I am targeting. I just want to use the assembly of the project and the console application will have all the necessary API explorer packages.

Is this possible?

Can I load an assembly and run Api explorer on it?

Answer 1

This code is for ASP.NET Core 2.0, but it may be of use to you. It relies on Swashbuckle.AspNetCore and Microsoft.AspNetCore.TestHost:

IWebHostBuilder builder = new WebHostBuilder()
    .UseStartup<Startup>()
    .ConfigureServices(services =>
    {
        services.AddSwaggerGen(opts =>
        {
            opts.SwaggerDoc("doc-name", new Info { Title = "Title", Version = "v1" });
        });
    });

JsonSerializerSettings mvcSerializerSettings;
SwaggerDocument document;

using (var testServer = new TestServer(builder))
{
    IOptions<MvcJsonOptions> mvcOptions = testServer.Host.Services.GetService<IOptions<MvcJsonOptions>>();
    mvcSerializerSettings = mvcOptions.Value.SerializerSettings;

    ISwaggerProvider swaggerProvider = testServer.Host.Services.GetService<ISwaggerProvider>();
    document = swaggerProvider.GetSwagger("doc-name");
}

// Reference: Swashbuckle.AspNetCore.Swagger/Application/SwaggerSerializerFactory.cs
var settings = new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
    Formatting = mvcSerializerSettings.Formatting,
    ContractResolver = new SwaggerContractResolver(mvcSerializerSettings),
};

string json = JsonConvert.SerializeObject(document, settings);

Where Startup is your project's Startup class. Here the project is directly referenced, but you should be able to load the assembly and consume it accordingly.

Answer 2

This is inspired by a swashbuckle sample, but is also possible using only ApiExplorer.

You can create an OWIN TestServer, create a HttpConfiguration, run your WebApi OWIN init code, and then create the ApiExplorer from the initialized HttpConfiguration. The only problem you might have is finding the WebApi portion of the startup code in the target assembly. In my case I'm referencing the WebAPi project in the same solution, so it's easier to call the relevant startup code.

private static Collection<ApiDescription> GetApiDescriptions()
{
  Collection<ApiDescription> descriptions = null;
  TestServer.Create(app => {
    var httpConfiguration = new HttpConfiguration();
    // This is the call to my webapi startup method in the target project, this may be tricky to find (using reflection) in your case
    new Startup().ConfigureWebApi(app, httpConfiguration);
    var apiExplorer = new ApiExplorer(httpConfiguration);
    httpConfiguration.EnsureInitialized();
    descriptions = apiExplorer.ApiDescriptions;
  });
  return descriptions;
}