Description
A simple RAML to HTML documentation generator, written for Node.js. Check raml2md for a RAML to Markdown generator.
RAML alternatives and similar libraries
Based on the "REST Frameworks" category.
Alternatively, view RAML alternatives based on common mentions on social networks and blogs.
-
Dropwizard
Opinionated framework for setting up modern web applications with Jetty, Jackson, Jersey and Metrics. -
rest.li
Framework for building robust, scalable RESTful architectures using type-safe bindings and asynchronous, non-blocking IO with an end-to-end developer workflow that promotes clean practices, uniform interface design and consistent data modeling. -
Swagger
Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. -
Rapidoid
A simple, secure and extremely fast framework consisting of embedded HTTP server, GUI components and dependency injection. -
Microserver
A convenient extensible Microservices plugin system for Spring & Spring Boot, with over 30 plugins and growing, that supports both micro-monolith and pure microservices styles. -
Restlet Framework
Pioneering framework with powerful routing and filtering capabilities, unified client and server API. -
Crnk
Implementation of the JSON API specification to build resource-oriented REST endpoints with sorting, filtering, paging, linking, object graphs, type-safety, bulk updates, integrations and more. -
StubbornJava
Unconventional Java code for building web servers / services without a framework. Think dropwizard but as a seed project instead of a framework. If this project had a theme it would be break the rules but be mindful of your decisions. -
Restler
Automatically generates a web service client at run time by analyzing its annotated Spring controller interface
Get performance insights in less than 4 minutes
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest. Visit our partner's website for more details.
Do you think we are missing an alternative of RAML or a related project?
Popular Comparisons
README
raml2html
A simple RAML to HTML documentation generator, written for Node.js, with theme support.
RAML version support
raml2html 4 and higher only support RAML 1.0 files. Please stick with raml2html 3.x for RAML 0.8 support.
Install
npm i -g raml2html
Themes
raml2html ships with a default theme, but you can install more from NPM. For example, to render RAML to Markdown, you can install the raml2html-markdown-theme theme:
npm i -g raml2html-markdown-theme
Search NPM for the "raml2html-theme" keyword (or use this link) to find more themes.
Usage
As a command line script
raml2html --help
raml2html example.raml > example.html
raml2html --theme raml2html-markdown-theme example.raml > example.html
raml2html --template my-custom-template.nunjucks -i example.raml -o example.html
As a library
Using the default theme, different themes, or your own Nunjucks templates
const raml2html = require('raml2html');
const configWithDefaultTheme = raml2html.getConfigForTheme();
const configForDifferentTheme = raml2html.getConfigForTheme('raml2html-markdown-theme');
const configWithCustomTemplate = raml2html.getConfigForTemplate('~/path/to/my-custom-template.nunjucks');
// source can either be a filename, url, or parsed RAML object
raml2html.render(source, configWithDefaultTheme).then(function(result) {
// Save the result to a file or do something else with the result
}, function(error) {
// Output error
});
Using your own processing function, for full control over the whole rendering process
/**
* config should be an object with at least an `processRamlObj` property which is a function that receives the raw RAML
* object and must return a promise with the result. You can do whatever you want in this function.
*
* You can also supply a postProcessHtml function that can for example minify the generated HTML.
*
* You can also supply a writeOutput function that takes over writing the output (to disk for example).
*
* You can also supply a setupNunjucks function that takes the env as its only parameter.
*/
raml2html.render(source, config).then(function(result) {
// Save the result to a file or do something else with the result
}, function(error) {
// Output error
});
See also example/script.js
for multiple examples of using raml2html as a library.
Gulp
You can use the raml2html directly from Gulp.
Example output
Please see the following links for live examples:
- https://rawgit.com/raml2html/default-theme/master/examples/helloworld.html
- https://rawgit.com/raml2html/default-theme/master/examples/world-music-api.html
Before you report a bug
If you get parsing errors, please do not report them to raml2html: it doesn't do the actual RAML parsing. Review the error and fix your RAML file, or open a new issue at raml-js-parser-2.
Contributing
raml2html is an open source project and your contribution is very much appreciated.
- Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
- Fork the repository on Github and make your changes on the develop branch (or branch off of it).
Run
npm run lint
before committing to check for common problems and auto format all code. - Add an example of the new feature to example.raml (if applicable)
- Send a pull request (with the develop branch as the target).
If your pull request is merged feel free to ask for push access. We want to get more maintainers! If you do have push access, please still work on feature branches and create pull requests, which then get reviewed. You can also review other people's pull requests and be involved in that way.
A big thank you goes out to everyone who helped with the project, the contributors and everyone who took the time to report issues and give feedback.
Local setup
To get the best environment to work on raml2html and the default theme, follow these steps.
- Checkout raml2html-default-theme's develop branch;
npm link
. - Checkout raml2html's develop branch; first
npm link raml2html-default-theme
and thennpm link
.
Now both projects are installed globally, but using the local development versions of both.
From the theme repo's example folder you can run the render-all-examples
script without problem.
Changelog
See changelog.md
License
raml2html is available under the MIT license. See the LICENSE file for more info.
*Note that all licence references and agreements mentioned in the RAML README section above
are relevant to that project's source code only.