v4 Update
v4 ServiceStack provides a number of new ways to customize the built-in Metadata pages:
Using the Virtual File System
ServiceStack's Virtual FileSystem by default falls back (i.e when no physical file exists) to looking for Embedded Resource Files inside dlls.
You can specify the number and precedence of which Assemblies it looks at with Config.EmbeddedResourceSources which by default looks at:
- The assembly that contains your AppHost
- ServiceStack.dll
The VFS now lets you completely replace built-in ServiceStack metadata pages and templates with your own by simply copying the metadata or HtmlFormat Template files you want to customize and placing them in your folder at:
/Templates/HtmlFormat.html // The auto HtmlFormat template
/Templates/IndexOperations.html // The /metadata template
/Templates/OperationControl.html // Individual operation template
Registering links on the Metadata pages
You can add links to your own Plugins in the metadata pages with:
appHost.GetPlugin<MetadataFeature>()
.AddPluginLink("swagger-ui/", "Swagger UI");
appHost.GetPlugin<MetadataFeature>()
.AddDebugLink("?debug=requestinfo", "Request Info");
AddPluginLink adds links under the Plugin Links section whilst AddDebugLink can be used by plugins only available during debugging or development.
Using Metadata Attributes
Many of the same attributes used in Swagger are also used in the metadata pages, e.g:
[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 = "GET 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; }
}
Older v3 Notes
ServiceStack's Metadata page allows limited customization via the EndpointHostConfig config settings (where all of ServiceStack configuration lives). E.g. you can change the Home page Body HTML and the Operations Page HTML in your AppHost with:
SetConfig(new EndpointHostConfig {
MetadataPageBodyHtml = "<p>HTML you want on the home page</p>",
MetadataOperationPageBodyHtml = "<p>HTML you want on each operation page</p>"
});
You can also add further metadata documentation for each Web Service by using the attributing the Request DTO with the [Description] attribute as done in the MoviesRest Example project:
[Description("GET or DELETE a single movie by Id. POST to create new Movies")]
[RestService("/movies", "POST,PUT,PATCH,DELETE")]
[RestService("/movies/{Id}")]
public class Movie
{
public int Id { get; set; }
public string ImdbId { get; set; }
public string Title { get; set; }
}
And what it looks like on the MoviesRest /metadata page.
