├── .gitignore ├── .npmignore ├── .travis.yml ├── Gruntfile.coffee ├── LICENSE ├── README.md ├── package.json ├── src └── raml2html.coffee └── test ├── fixtures └── song.raml └── test.coffee /.gitignore: -------------------------------------------------------------------------------- 1 | # Mac shit 2 | .DS_Store 3 | 4 | # Logs 5 | logs 6 | *.log 7 | 8 | # Runtime data 9 | pids 10 | *.pid 11 | *.seed 12 | 13 | # Directory for instrumented libs generated by jscoverage/JSCover 14 | lib-cov 15 | 16 | # Coverage directory used by tools like istanbul 17 | coverage 18 | 19 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 20 | .grunt 21 | 22 | # Compiled binary addons (http://nodejs.org/api/addons.html) 23 | build/Release 24 | 25 | # Dependency directory 26 | # Deployed apps should consider commenting this line out: 27 | # see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git 28 | node_modules 29 | 30 | # Coffee genereated 31 | tasks 32 | 33 | assets 34 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | src/ 2 | test/ 3 | .travis.yml 4 | Gruntfile.coffee 5 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | language: node_js 3 | cache: 4 | directories: 5 | - node_modules 6 | notifications: 7 | email: false 8 | node_js: 9 | - '4' 10 | before_install: 11 | - npm i -g npm@^2.0.0 12 | before_script: 13 | - npm prune 14 | after_success: 15 | - npm install github:cybertk/condition-travis-allow-pr 16 | - npm run semantic-release 17 | branches: 18 | except: 19 | - "/^v\\d+\\.\\d+\\.\\d+$/" 20 | -------------------------------------------------------------------------------- /Gruntfile.coffee: -------------------------------------------------------------------------------- 1 | module.exports = (grunt) -> 2 | 3 | require('time-grunt') grunt 4 | 5 | ### 6 | Dynamically load npm tasks 7 | ### 8 | require('jit-grunt') grunt 9 | 10 | grunt.loadNpmTasks('grunt-contrib-coffee') 11 | grunt.loadNpmTasks('grunt-mocha-test') 12 | 13 | # Actually load this plugin's task(s). 14 | grunt.loadTasks('tasks') 15 | 16 | grunt.initConfig 17 | 18 | # Watching changes files *.js, 19 | watch: 20 | all: 21 | files: [ 22 | "Gruntfile.coffee" 23 | "src/**/*.coffee" 24 | "test/**/*.coffee" 25 | ] 26 | tasks: [ 27 | "coffee" 28 | "mochaTest" 29 | ] 30 | options: 31 | nospawn: true 32 | 33 | coffee: 34 | compile: 35 | expand: true, 36 | flatten: true, 37 | src: ['src/*.coffee'], 38 | dest: 'tasks/', 39 | ext: '.js' 40 | 41 | mochaTest: 42 | test: 43 | options: 44 | reporter: 'spec' 45 | require: 'coffee-script/register' 46 | src: ['test/**/*.coffee'] 47 | 48 | # Before generating any new files, remove any previously-created files. 49 | clean: 50 | tests: ['assets'] 51 | 52 | # Configuration to be run (and then tested). 53 | raml2html: 54 | compileDefault: 55 | expand: true, 56 | flatten: true, 57 | src: ['test/fixtures/song.raml'], 58 | dest: 'assets/', 59 | ext: '.html' 60 | 61 | 62 | grunt.registerTask "default", [ 63 | "watch" 64 | ] 65 | 66 | grunt.registerTask "test", [ 67 | "coffee" 68 | "raml2html" 69 | "mochaTest" 70 | ] 71 | 72 | return 73 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2014-2015 Quanlong He 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## grunt-raml2html 2 | 3 | > Compile RAML to HTML 4 | 5 | [![npm](https://img.shields.io/npm/v/grunt-raml2html.svg)](https://www.npmjs.com/package/grunt-raml2html) 6 | [![Build Status](http://img.shields.io/travis/cybertk/grunt-raml2html.svg?style=flat)](https://travis-ci.org/cybertk/grunt-raml2html) 7 | [![Dependency Status](https://david-dm.org/cybertk/grunt-raml2html.svg)](https://david-dm.org/cybertk/grunt-raml2html) 8 | [![devDependency Status](https://david-dm.org/cybertk/grunt-raml2html/dev-status.svg)](https://david-dm.org/cybertk/grunt-raml2html#info=devDependencies) 9 | [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) 10 | 11 | ## Getting Started 12 | This plugin requires Grunt `~0.4.5` 13 | 14 | If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command: 15 | 16 | ```shell 17 | npm install grunt-raml2html --save-dev 18 | ``` 19 | 20 | Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript: 21 | 22 | ```js 23 | grunt.loadNpmTasks('grunt-raml2html'); 24 | ``` 25 | 26 | ## The "raml2html" task 27 | 28 | ### Overview 29 | In your project's Gruntfile, add a section named `raml2html` to the data object passed into `grunt.initConfig()`. 30 | 31 | ```js 32 | grunt.initConfig({ 33 | raml2html: { 34 | all: { 35 | options: { 36 | // Task-specific options go here. 37 | }, 38 | default: { 39 | // Target-specific file lists and/or options go here. 40 | } 41 | } 42 | }, 43 | }); 44 | ``` 45 | 46 | ### Options 47 | 48 | #### options.separator 49 | Type: `String` 50 | Default value: `', '` 51 | 52 | A string value that is used to do something with whatever. 53 | 54 | #### options.punctuation 55 | Type: `String` 56 | Default value: `'.'` 57 | 58 | A string value that is used to do something else with whatever else. 59 | 60 | ### Usage Examples 61 | 62 | #### Default Options 63 | In this example, the default options are used to do something with whatever. So if the `testing` file has the content `Testing` and the `123` file had the content `1 2 3`, the generated result would be `Testing, 1 2 3.` 64 | 65 | ```js 66 | grunt.initConfig({ 67 | raml2html: { 68 | all: { 69 | files: { 70 | 'dest/api.html': ['api.raml'], 71 | } 72 | } 73 | }, 74 | }); 75 | ``` 76 | 77 | #### Custom Options 78 | In this example, custom options are used to do something else with whatever else. So if the `testing` file has the content `Testing` and the `123` file had the content `1 2 3`, the generated result in this case would be `Testing: 1 2 3 !!!` 79 | 80 | ```js 81 | grunt.initConfig({ 82 | raml2html: { 83 | all: { 84 | options: { 85 | separator: ': ', 86 | punctuation: ' !!!' 87 | }, 88 | files: { 89 | 'dest/api.html': ['src/github.raml'], 90 | } 91 | } 92 | }, 93 | }); 94 | ``` 95 | 96 | #### Custom Template 97 | 98 | Custom templates can be loaded using the following. Both mainTemplate and templatesPath are required in this case. Other templates, such as resource.nunjucks and item.nunjucks are now seen as part of the main template. Therefore they cannot be set individually. 99 | 100 | ```js 101 | grunt.initConfig({ 102 | raml2html: { 103 | all: { 104 | options: { 105 | mainTemplate: 'template.nunjucks', 106 | templatesPath: './my/custom/path' 107 | }, 108 | files: { 109 | 'dest/api.html': ['src/github.raml'], 110 | } 111 | } 112 | }, 113 | }); 114 | ``` 115 | 116 | ## Contributing 117 | In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [Grunt](http://gruntjs.com/). 118 | 119 | 120 | [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/cybertk/grunt-raml2html/trend.png)](https://bitdeli.com/free "Bitdeli Badge") 121 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "grunt-raml2html", 3 | "description": "Grunt plugin to compile raml to html", 4 | "directories": { 5 | "test": "test" 6 | }, 7 | "scripts": { 8 | "prepublish": "grunt coffee", 9 | "test": "grunt coffee && grunt test", 10 | "semantic-release": "semantic-release pre && npm publish && semantic-release post" 11 | }, 12 | "repository": { 13 | "type": "git", 14 | "url": "https://github.com/cybertk/grunt-raml2html.git" 15 | }, 16 | "keywords": [ 17 | "gruntplugin", 18 | "raml", 19 | "raml2html", 20 | "grunt" 21 | ], 22 | "author": { 23 | "name": "Quanlong" 24 | }, 25 | "license": "MIT", 26 | "bugs": { 27 | "url": "https://github.com/cybertk/grunt-raml2html/issues" 28 | }, 29 | "homepage": "https://github.com/cybertk/grunt-raml2html", 30 | "devDependencies": { 31 | "chai": "~3.5.0", 32 | "coffee-script": "~1.11.1", 33 | "grunt": "~1.0.1", 34 | "grunt-contrib-coffee": "~1.0.0", 35 | "grunt-contrib-watch": "~1.0.0", 36 | "grunt-mocha-test": "~0.13.2", 37 | "grunt-cli": "~1.1.0", 38 | "jit-grunt": "~0.10.0", 39 | "mocha": "~3.1.2", 40 | "time-grunt": "~1.4.0", 41 | "semantic-release": "^6.3.0" 42 | }, 43 | "dependencies": { 44 | "async": "~2.1.2", 45 | "raml2html": "~6.1.0" 46 | }, 47 | "peerDependencies": { 48 | "grunt": ">=0.4.0" 49 | }, 50 | "release": { 51 | "verifyConditions": "./node_modules/@semantic-release/condition-travis-allow-pr" 52 | } 53 | } 54 | -------------------------------------------------------------------------------- /src/raml2html.coffee: -------------------------------------------------------------------------------- 1 | raml2html = require 'raml2html' 2 | async = require 'async' 3 | 4 | module.exports = (grunt) -> 5 | grunt.registerMultiTask 'raml2html', 'Compile raml files to html', -> 6 | done = @async() 7 | {mainTemplate, templatesPath} = @options() 8 | mainTemplate ?= false 9 | templatesPath ?= false 10 | 11 | async.eachSeries @files, ({src, dest}, next) -> 12 | grunt.log.debug "Compiling #{src} to #{dest}" 13 | 14 | [source] = src 15 | 16 | config = raml2html.getDefaultConfig mainTemplate, templatesPath 17 | 18 | raml2html.render source, config 19 | .then (html)-> 20 | grunt.file.write dest, html 21 | grunt.log.writeln "file #{dest.cyan} created" 22 | next() 23 | .fail (error)-> 24 | grunt.log.error error 25 | done false 26 | 27 | grunt.log.debug "Compiled #{src}" 28 | 29 | , done 30 | 31 | fileCount = @files.length 32 | grunt.log.ok "#{fileCount} #{grunt.util.pluralize fileCount, 'file/files'} compiled to html." 33 | 34 | -------------------------------------------------------------------------------- /test/fixtures/song.raml: -------------------------------------------------------------------------------- 1 | #%RAML 0.8 2 | 3 | title: World Music API 4 | baseUri: http://example.api.com/{version} 5 | version: v1 6 | traits: 7 | - paged: 8 | queryParameters: 9 | pages: 10 | description: The number of pages to return 11 | type: number 12 | /songs: 13 | is: [ paged ] 14 | get: 15 | queryParameters: 16 | genre: 17 | description: filter the songs by genre 18 | post: 19 | /{songId}: 20 | get: 21 | responses: 22 | 200: 23 | body: 24 | application/json: 25 | schema: | 26 | { "$schema": "http://json-schema.org/schema", 27 | "type": "object", 28 | "description": "A canonical song", 29 | "properties": { 30 | "title": { "type": "string" }, 31 | "artist": { "type": "string" } 32 | }, 33 | "required": [ "title", "artist" ] 34 | } 35 | example: | 36 | { "title": "A Beautiful Day", "artist": "Mike" } 37 | application/xml: 38 | delete: 39 | description: | 40 | This method will *delete* an **individual song** 41 | -------------------------------------------------------------------------------- /test/test.coffee: -------------------------------------------------------------------------------- 1 | chai = require 'chai' 2 | 3 | chai.should() 4 | 5 | fs = require 'fs' 6 | 7 | path = (filename) -> 8 | "#{__dirname}/../#{filename}" 9 | 10 | # Actual test is started by `grunt raml2html`, here we only check the results of grunt task 11 | describe 'raml2html task', -> 12 | 13 | before (done) -> 14 | # Actual test is started by `grunt raml2html`. 15 | done() 16 | 17 | describe 'compareDefault', -> 18 | 19 | it 'should compiles valid raml files to html', -> 20 | fs.existsSync(path 'assets/song.html').should.be.ok 21 | --------------------------------------------------------------------------------