Adding Swagger Metadata and Help UI to a Mobile App

Sandeep Chakradhari edited this page Jan 11, 2017 · 10 revisions

NOTE: The 0.3.157.1 version of Microsoft.Azure.Mobile.Server.Swagger depends on a version the swagger-ui JavaScript library that has a security vulnerability. See https://nodesecurity.io/advisories/126.

We recommend that you uninstall Swagger on your production Azure Mobile backends. After doing so, confirm that your application code no longer includes a reference to the Swashbuckle.Core package. Then republish your application.

We'll update this page when there's a package that resolves the issue.

Added with Pull Request #73. Available in Release 1.1.157.1.

The Microsoft.Azure.Mobile.Server.Swagger Nuget package uses Swagger and Swashbuckle to add documentation and API Explorer capability to your Mobile App:

  • Swagger provides a way to document a RESTful API as well as a way to generate live Help pages for performing operations against your API.
  • Swashbuckle provides an easy way to add Swagger metadata and UI to a Web API application.

If you follow the Swashbuckle documentation and enable Swagger and Swagger UI, you'll quickly see that some things don't appear correct. We've added some helpers in the Microsoft.Azure.Mobile.Server.Swagger NuGet package to fix those things. After adding that package, do the following (assuming you are starting from the quickstart):

  1. In the App_Start folder add a new class named Startup.Swagger.cs.
  2. Paste this in:

    using System.Web.Http;
    using System.Web.Http.Description;
    using Microsoft.Azure.Mobile.Server;
    using Microsoft.Azure.Mobile.Server.Swagger;
    using Swashbuckle.Application;
    
    namespace _YOUR_NAMEPACE_
    {
    public partial class Startup
    {
        public static void ConfigureSwagger(HttpConfiguration config)
        {
            // Use the custom ApiExplorer that applies constraints. This prevents
            // duplicate routes on /api and /tables from showing in the Swagger doc.
            config.Services.Replace(typeof(IApiExplorer), new MobileAppApiExplorer(config));
            config
               .EnableSwagger(c =>
               {
                   c.SingleApiVersion("v1", "myService");
    
                   // Tells the Swagger doc that any MobileAppController needs a
                   // ZUMO-API-VERSION header with default 2.0.0
                   c.OperationFilter<MobileAppHeaderFilter>();
    
                   // Looks at attributes on properties to decide whether they are readOnly.
                   // Right now, this only applies to the DatabaseGeneratedAttribute.
                   c.SchemaFilter<MobileAppSchemaFilter>();
               })
               .EnableSwaggerUi();
        }
    }
    }
    
  3. In Startup.MobileApp.cs, right after app.UseWebApi(config);, call ConfigureSwagger(config);
  4. Press F5 to launch your site locally.
  5. Navigate to https://localhost:{port}/swagger

You should now view the Swagger UI.

App Service Authentication

If you want any API using an [Authorize] attribute to support login from the Swagger UI page, you will need to add a few more lines to your Swagger configuration:

  1. In the EnableSwagger code block, add this:

    // 1. Adds an OAuth implicit flow description that points to App Service Auth with the specified provdier
    // 2. Adds a Swashbuckle filter that applies this Oauth description to any Action with [Authorize]
    c.AppServiceAuthentication("https://{mysite}.azurewebsites.net/", "{provider}");
    
  2. Remove the line with .EnableSwaggerUi(); and replace with:

    .EnableSwaggerUi(c =>
    {
       c.EnableOAuth2Support("na", "na", "na");
    
       // Replaces some javascript files with specific logic to:
       // 1. Do the OAuth flow using the App Service Auth parameters
       // 2. Parse the returned token
       // 3. Apply the token to the X-ZUMO-AUTH header
       c.MobileAppUi(config);
    });
    

When enabled, you will any Authorized API will have a small toggle switch in the upper right. Clicking that should take you to the URL registered by the call to AppServiceAuthentication. For example, if I used c.AppServiceAuthentication("https://mysite.azurewebsites.net/", "facebook");, and I had properly set up App Service Authentication for Facebook login support, a new tab will open taking you to the Facebook login page.

If you're running your site on localhost, you'll notice that after logging into facebook that you'll end up staring a site saying "You have successfully signed in" but not much else happens.

This is because the Swagger UI asked App Service Authentication to redirect back to localhost when it was complete but App Service Authentication will only redirect back to sites that have been explicitly allowed.

There's currently no way to do this via the Azure portal but you can add additional redirects by using Azure Resource Explorer. From here, you can navigate to your Resource Group and Site. Once you've made it to your site, expand config and select authSettings. Then, add http://localhost:{port}/swagger/ui/o2c-html to the list of allowedExternalRedirectUrls. Click Put and try again. This time you should be redirected back to the Swagger UI and your requests to Authorized APIs should go through.

The redirect should work without any changes when running the Swagger UI from a deployed site as the requested redirect URI will be coming from the same domain.