Edit on GitHub

Open API

Open API is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. ServiceStack implements the OpenAPI Spec back-end and embeds the Swagger UI front-end in a separate plugin which is available under OpenAPI NuGet package:

PM> Install-Package ServiceStack.Api.OpenApi

Installation

You can enable Open API by registering the OpenApiFeature plugin in AppHost with:

public override void Configure(Container container)
{
    ...
    Plugins.Add(new OpenApiFeature());

    // Uncomment CORS feature if it needs to be accessible from external sites 
    // Plugins.Add(new CorsFeature()); 
    ...
}

Then you will be able to view the Swagger UI from /swagger-ui/. A link to Swagger UI will also be available from your /metadata Metadata Page.

Open API Attributes

Each route could have a separate summary and description. You can set it with Route attribute:

[Route("/hello", Summary = @"Default hello service.", 
    Notes = "Longer description for hello service.")]

You can set specific description for each HTTP method like shown below:

[Route("/hello/{Name}", "GET", Summary="Says 'Hello' to provided Name", 
    Notes = "Longer description of the GET method which says 'Hello'")]
[Route("/hello/{Name}", "POST", Summary="Says 'Hello' to provided Name", 
    Notes = "Longer description of the POST method which says 'Hello'")]

You can further document your services in the OpenAPI with the new [Api] and [ApiMember] annotation attributes, e,g: Here’s an example of a fully documented service:

[Api("Service Description")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger/{Name}", "GET", Summary = "GET Summary", Notes = "Notes")]
[Route("/swagger/{Name}", "POST", Summary = "POST Summary", Notes="Notes")]
public class MyRequestDto
{
    [ApiMember(Name="Name", Description = "Name Description",
        ParameterType = "path", DataType = "string", IsRequired = true)]
    [ApiAllowableValues("Name", typeof(Color))] //Enum
    public string Name { get; set; }
}

Please note, that if you used ApiMember.DataType for annotating SwaggerFeature then you need to change the types to OpenAPI type when migrating to OpenApiFeature. For example, annotation of

[ApiMember(DataType="int")]

need to be changed to

[ApiMember(DataType="integer", Format="int32")]

Here is the table for type migration

Swagger Type (DataType) OpenAPI Type (DataType) OpenAPI Format (Format)
Array array  
boolean boolean  
byte integer int
Date string date
  string date-time
double number double
float number float
int integer int32
long integer int64
string string  

You can Exclude properties from being listed in OpenAPI with:

[IgnoreDataMember]

Exclude properties from being listed in OpenAPI Schema Body with:

[ApiMember(ExcludeInSchema=true)]

Exclude Services from Metadata Pages

To exclude entire Services from showing up in OpenAPI or any other Metadata Services (i.e. Metadata Pages, Postman, NativeTypes, etc), annotate Request DTO’s with:

[Exclude(Feature.Metadata)]
public class MyRequestDto { ... }

Swagger UI Route Summaries

The Swagger UI groups multiple routes under a single top-level route that covers multiple different services sharing the top-level route which can be specified using the RouteSummary dictionary of the OpenApiFeature plugin, e.g:

Plugins.Add(new OpenApiFeature {
    RouteSummary = {
        { "/top-level-path", "Route Summary" }
    }
});

Operation filters

You can override operation or parameter definitions by specifying the appropriate filter in plugin configuration:

Plugins.Add(new OpenApiFeature
{
    OperationFilter = (verb, operation) => operation.Tags.Add("all operations")
});

Available configuration options:

  • ApiDeclarationFilter - allows to modify final result of returned OpenAPI json
  • OperationFilter - allows to modify operations
  • SchemaFilter - allows to modify OpenAPI schema for user types
  • SchemaPropertyFilter - allows to modify propery declarations in OpenAPI schema

Properties naming conventions

You can control naming conventions of generated properties by following configuration options:

  • UseCamelCaseSchemaPropertyNames - generate camel case property names
  • UseLowercaseUnderscoreSchemaPropertyNames - generate underscored lower cased property names (to enable this feature UseCamelCaseModelPropertyNames must also be set)

Example:

Plugins.Add(new OpenApiFeature
{
    UseCamelCaseSchemaPropertyNames = true,
    UseLowercaseUnderscoreSchemaPropertyNames = true
});

Change default Verbs

If left unspecified, the [Route] attribute allows Services to be called from any HTTP Verb which by default are listed in the Open API specification under the most popular HTTP Verbs, namely GET, POST, PUT and DELETE.

This can be modified with AnyRouteVerbs which will let you specify which Verbs should be generated for ANY Routes with unspecified verbs, e.g. we can restrict it to only emit routes for GET and POST Verbs with:

Plugins.Add(new OpenApiFeature
{
    AnyRouteVerbs =  new List<string> { HttpMethods.Get, HttpMethods.Post }
});

Miscellaneous configuration options

  • DisableAutoDtoInBodyParam - disables adding body parameter for request DTO to operations
  • LogoUrl - url of the logo image for Swagger UI

Example:

Plugins.Add(new OpenApiFeature
{
    DisableAutoDtoInBodyParam = true
});

Virtual File System

The docs on the Virtual File System shows how to override embedded resources:

Overriding OpenAPI Embedded Resources

ServiceStack’s Virtual File System supports multiple file source locations where you can override OpenAPI’s embedded files by including your own custom files in the same location as the existing embedded files. This lets you replace built-in ServiceStack embedded resources with your own by simply copying the /swagger-ui files you want to customize and placing them in your Website Directory at:

/swagger-ui
/css
/images
/lib
index.html

Basic Auth in OpenAPI

Users can call protected Services using the Username and Password fields in Swagger UI. Swagger UI sends these credentials with every API request using HTTP Basic Auth, which can be enabled in your AppHost with:

Plugins.Add(new AuthFeature(...,
      new IAuthProvider[] { 
        new BasicAuthProvider(), //Allow Sign-ins with HTTP Basic Auth
      }));

To login, you need to click “Authorize” button.

And then enter username and password.

Also you can click “Try it out” button on services, which requires authentication and browser will prompt a window with user/password field for entering basic auth credentials.

Alternatively you can authenticate outside Swagger (e.g. via an OAuth Provider) which will also let you call protected Services in /swagger-ui.

Generating AutoRest client

You can use OpenAPI plugin to automatically generate client using Autorest. To use AutoRest first install it from npm:

npm install -g autorest

Then you need to download the Open API specification for your Services using a tool like curl:

curl http://your.domain/openapi > openapi.json

Or using iwr if you have PowerShell installed:

iwr http://your.domain/openapi -o openapi.json

You can then use the openapi.json with autorest to generate a client for your API in your preferred language, e.g:

autorest --latest-release -Input openapi.json -CodeGenerator CSharp -OutputDirectory AutoRestClient -Namespace AutoRestClient

This will generate directory containing your model types and REST operations that you can use with the generated client, e.g:

using (var client = new SampleProjectAutoRestClient("http://localhost:20000"))
{
    var dto = new SampleDto { /* .... */ }; 
    var result = client.SampleOperation.Post(body: dto);

    // process result
}

AutoRest clients will allow usage of tooling that have adopted AutoRest and is a good stop gap solution for generating native clients for languages that Add ServiceStack Reference doesn’t support yet like Python and Ruby.

AutoRest Generated Clients vs Add ServiceStack Reference

However AutoRest generated clients are similar to WCF Service Reference generated clients where it generates RPC-style Clients that emits both implementation logic and models for sending each request that’s coupled to external HttpClient and JSON.NET dependencies. This approach generates significantly more code generation that populates a directory containing multiple implementation and Model classes generated for each Service.

In contrast Add ServiceStack Reference adopts the venerable Data Transfer Object, Gateway and Remote Facade Service patterns where it only needs to generate clean, implementation-free DTO models that it captures in a single source file for all supported languages.

The generated DTOs are cleaner and more reusable where it isn’t coupled to any Serialization implementation and can be reused in any of ServiceStack’s message-based Service Clients and Serialization Formats or different Service Gateway implementations. The models are also richer where it’s able to include additional metadata attributes and marker interfaces that isn’t possible when tunneling through a generic API specification.

The use of intelligent generic Service Clients will always be able to provide a richer more productive development experience that can enable higher-level, value-added functionality like Structured Error Handling, Smart HTTP Caching, Auto Batching, Encrypted Messaging, AutoQuery Streaming, Request Compression, integrated authentication and lots more.

Known issues

Autorest generated clients do not support application/octet-stream MIME type, which is used when service returns byte[] array. You can track this issue on Github.

Publish Azure Management API

Login to Azure Portal and search for API management service.

Choose API management service. In opened window click Add button.

Fill the creation form. Put your own values in Name, Resource Group, Organization name and Administrator email. When creation form will be ready, click Create button.

Wait while Management API will be activated. It can take more than forty minutes. When it ready click on created API management resource.

In opened window click APIs - PREVIEW menu item on the left pane.

Choose OpenAPI specification in Add API section.

Fill the url with location of you services, ended with /openapi or just click Upload button and upload OpenAPI json definition, which is available at /openapi path of your services.

After successfull import you should see list of available operations for your services