/servicestack-introspec-raml

A documentation and specification plugin for ServiceStack that generates output in RAML

Primary LanguageC#OtherNOASSERTION

Logo ServiceStack.IntroSpec.Raml

Build status NuGet version

A plugin for ServiceStack that uses output from ServiceStack.IntroSpec to generate documentation that complies to the RAML standard.

Formats

The ServiceStack.IntroSpec plugin uses introspection on a number of different sources to generate a set of universal documentation DTOs. ServiceStack.IntroSpec.Raml converts these DTOs to the RAML 0.8 specification.

RAML is a YAML-based specification for describing RESTful API's.

Quick Start

Install the package https://www.nuget.org/packages/ServiceStack.IntroSpec

PM> Install-Package ServiceStack.IntroSpec.Raml

This plugin has a dependency on the ApiSpecFeature plugin from ServiceStack.IntroSpec but apart from that it is added like any other plugin.

public override void Configure(Container container)
{
	// Dependency
	Plugins.Add(new ApiSpecFeature(....));
	
	// Register plugin
    Plugins.Add(new RamlFeature());
}

Services

The plugin registers a service at /spec/raml/0.8. Calling this service will return output with content-type of application/raml+yaml that conforms to v0.8 of the RAML specification.

Support for v1.0 will be added at a later date

Restrictions

There are a number of areas that are not yet completed, primarily due to data not yet being available via ServiceStack.IntroSpec.

  • Named Parameters - no support for Pattern, MinLength, MaxLength, Example or Default.
  • Schemas are repeated and only rendered for JSON.
  • No security information is output.
  • Nested resources will all be rendered as main resources.

The output is valid when tested using the RAML Api-Console. There are no 'MUST' sections missing so the generated data should be usable in any RAML parser.