DropWizard RAML API Resource Bundle

This bundle allows a RAML specification to be attached to the resources of the service, exposing a human-readable, HTML representation of the RAML specification on the /api resource.

EOL Notice

This library has reached it's conclusion and it's concepts have been migrated into the new DropWizard RAML project. Specifically, to migrate from this view to the new view, refer to the DropWizard RAML API Docs library.

Disclaimer

This bundle supports both RAML 1.0 and RAML 0.8 but not all features of the specification language have been implemented in the view.

If you wish to include a missing feature, either raise an issue and I will address it when time permits or fork the project and make a pull request.

As this bundle now uses the newer raml-parser-2 library, Mulesoft have implemented some stricter controls over the specification structure, even for RAML 0.8. This means some older specification files may need to be updated to meet requirements.

Maven Central

<dependency>
    <groupId>net.ozwolf</groupId>
    <artifactId>dropwizard-raml-view</artifactId>
    <version>${current.version}</version>
</dependency>

Compatibility

The following versions are available via Maven Central:

• DropWizard 1.2.+ (with RAML 0.8 and 1.0 support) - Version 1.2.1.0
• DropWizard 1.1.+ (with RAML 0.8 and 1.0 support) - Version 1.1.1.0
• DropWizard 1.0.+ (with RAML 0.8 and 1.0 support) - Version 1.0.2.0
• DropWizard 0.9.2 (with RAML 0.8 support) - Version 0.9.2.1

While versions have not been deployed to Maven Central, older DropWizard versions with RAML 0.8 compatibility tags are available, though they are EOL without support. To use these, clone the repository, switch to the branch in question and use a mvn clean install to install it locally or create a package that can be uploaded to your own repository.

• DropWizard 0.8
• DropWizard 0.7

Endpoints

The following endpoints will be made available on your service:

• /api - The API specification as a HTML viewable endpoint.
• /api/raw - The API specification as it's raw YAML format. Note: At present, this resource is unavailable due to the RamlEmitter functionality of the original RAML Parser library not being implemented in the newer library. Please refer to this issue for further information.

Example Usage

To add this bundle to your service and expose a RAML specification under the /api resource. The bundle will differentiate between version 0.8 and version 1.0 RAML specifications automatically.

bootstrap.addBundle(RamlView.bundle("apispecs/apispecs.raml"));

Functionality Caveat

This project currently provides functionality that meet my usage needs for RAML specifications. It is by no means a comprehensive HTML representation of the RAML specification. This means particular components that other people need will be missing.

RAML Specification

• RAML 1.0 Documentation
• RAML 0.8 Documentation

Contributions

Contributions to this project are welcome.

Dependencies

This project uses the following dependency projects:

• RAML Java Parser 2
• DropWizard
• Commons Language 3
• Commons Codec
• Markdown4j