Open Api Specification

Our developers love a good openAPI Spec to work with, and we hope you do as well.

We have made it easy for you and created an NuGet package called Ucommerce.Headless.Documentation, this contains an OWIN extension, to set up API documentation:

    public void Configure(Owin.IAppBuilder appBuilder)
    {
        Ucommerce.Headless.Documentation.ApplicationBuilderExtensions.UseUcommerceDocumentation(appBuilder);
    }
    

See https://{yourdomain}/swagger, you will see the api-ref and you will be able to download a json file with the documentation.

Configure Umbraco - The complete guide

Per default Umbraco already uses owin, you just have to do some smaller changes to your project. This is a small guide with a few steps how to do so:

Step 1 - Creating a startup.cs

To be able to run owin middlewares you will need to overwrite the default Umbraco startup file. First thing to do is to create a new file, in this example called Startup.cs.

    using System.Web.Http;
    using Microsoft.Owin;
    using Owin;
    using Ucommerce.Headless.Documentation;
    using UcommerceCodeSamples.Headless;
    using Umbraco.Web;
    
    [assembly: OwinStartup("Startup", typeof(Startup))]
    
    namespace UcommerceCodeSamples.Headless
    {
        public class Startup : UmbracoDefaultOwinStartup
        {
            protected override void ConfigureMiddleware(IAppBuilder app)
            {
                base.ConfigureMiddleware(app);
    
                var config = new HttpConfiguration();
    
                app.UseUcommerceDocumentation();
    
                app.UseWebApi(config);
    
                config.MapHttpAttributeRoutes();
                config.EnsureInitialized();
            }
        }
    }

Step 2 - Adding it to web.config

To let owin pick-up your startup file you will need to specify that in web.config. In the class we just created on line 7 take the OwinStartup, FriendlyName. In our case it is Startup and paste it into web.config

    
      <appSettings>
        <add key="owin:appStartup" value="Startup" />
      </appSettings>
    

Step 3 - Let's see it in action

Your setup should now be complete and you should be able to hit http(s)://{yourdomain}/swagger.

Generating a client

OpenAPI Spec is a powerful tool, with that in your hands you can auto-generate the entire data layer of your application. We recommend that you take a look at NSwag. It contains generators for C#, Typescript and more.

Note: We recommend disabling OpenAPI Spec in production.