Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nidi3/raml-doc
Demo for a part of the GitHub API
https://github.com/nidi3/raml-doc
raml raml-documentation
Last synced: 13 days ago
JSON representation
Demo for a part of the GitHub API
- Host: GitHub
- URL: https://github.com/nidi3/raml-doc
- Owner: nidi3
- License: apache-2.0
- Created: 2015-07-08T21:00:53.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-06-02T12:50:56.000Z (over 7 years ago)
- Last Synced: 2024-12-17T14:48:40.311Z (17 days ago)
- Topics: raml, raml-documentation
- Language: Java
- Homepage: http://nidi3.github.io/raml-doc/github/output
- Size: 9.62 MB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
raml-doc [](https://travis-ci.org/nidi3/raml-doc)
===========
Generate an HTML documentation of a RAML file.
Send test requests to the service directly from within the documentation.
### Usage as standalone tool
The documentation can be generated statically using the command line interface.
##### maven
Download raml-doc-standalone either [manually](http://repo1.maven.org/maven2/guru/nidi/raml/raml-doc-standalone/)
or using maven, then execute
```
java -jar raml-doc-standalone.jar
```
##### npm
Install raml-doc from npm with `sudo npm install raml-doc -g`
Run it with `raml-doc `
### Usage as a servlet
The documentation can also be generated from within a web application.
Add this to web.xml
```xml
raml-doc
guru.nidi.raml.doc.servlet.RamlDocServlet
ramlLocations
classpath://api/myRaml.raml
raml-doc
/api/*
```
and the documentation is generated at startup and will be available directly from your application.
The available config parameters are the following:
Name | Meaning | Values
-----|---------|-------
ramlLocations | Comma separated list of RAML files. | Protocols like `file://`, `classpath://`, `http://` are supported.
features | Comma separated list of features to enable. | Features are:
`online`: The RAML documentation is available through the application,
`download`: The documentation provides a download link to the RAML file,
`tryout`: The API can be tried out interactively from within the documentation,
`docson`: Use [Docson](https://github.com/lbovet/docson) to display JSON schemas.
baseUri | The URL the test requests should be sent to (overrides the baseUri setting in the RAML file). |
baseUriParameters | Set the parameter values of the baseUri in the RAML file. | The format is `parameter=value,...`.
Special values are `$host` and `$path` which are replaced by the actual host and path of the running servlet.
customization | The location where the customized `favicon.ico`, `custom-variables.less`, `custom-style.less` should be loaded from. | For the supported protocols, see ramlLocations parameter. If not given, the first ramlLocation is used.
Another possibility is to subclass RamlDocServlet and override the configuration methods.
### Resulting HTML
The resulting HTML supports the following:
- Select a method by using an anchor, e.g. `res.html#get`
- These query parameters:
Name | Meaning | Value
-----|---------|------
expanded | Which resources in the resource tree on the left should be expanded. | Can be empty (all resources are expanded) or a comma separated list of resource names.
u_* | A URI parameter value to predefine. | The value for the parameter.
q_* | A query parameter value to predefine. | The value for the parameter.
h_* | A header value to predefine. | The value for the header.
f_* | A form parameter value to predefine. | The value for the parameter.
method | Which method should be selected. (Same as anchor but without scolling.) | GET, POST, PUT, DELETE
run | If a request of the selected method should be sent to the server. | none
### Demo
Documentation of a [subset of the GitHub API](http://nidi3.github.io/raml-doc/github/output/index.html).