Skip to content

Latest commit

 

History

History
808 lines (601 loc) · 18.8 KB

example.md

File metadata and controls

808 lines (601 loc) · 18.8 KB
Raw

test v0.13.0

RESTful web API Documentation Generator

Markdown

Markdown

Back to top

Enable markdown for all description fields.

This text is in a separate p.

  • List 1
  • List 2

Multiline markdown text, output in one line.

GET /markdown/:id

Parameters - Parameter

Name Type Description
param1 String

This is a markdown apiParam

Separate line.

Example

Example

Back to top

Extended usage of @apiExample with different example types.

GET /example/

Examples

PHP Example (new)

echo 'This is the content. (new)';

JS Example

console.log('This is the content.');

Success response example

Success response example - PHP Success Example (new)

echo 'This is the success content. (new)';

Success response example - JS Success Example

console.log('This is the success content.');

Error response example

Error response example - PHP Error Example

echo 'This is the error content.';

Error response example - JS Error Example

console.log('This is the error content.');

Define

Define

Back to top

Example of @apiDefine and @apiUse

GET /define

Parameters - Parameter

Name Type Description
field3

This is Field 3 (local).
field1

This is Field 1.
field2

This is Field 2.

Deprecated

Deprecated + content

Back to top

This is a deprecated hint with a link to the new method.

GET /deprecated/bar/:id

Parameters - Parameter

Name Type Description
param1

Parameter and description.

Deprecated

Back to top

This is a simple deprecated hint.

GET /deprecated/foo/:id

Parameters - Parameter

Name Type Description
param1

Parameter and description.

Escape

Escape Example

Back to top

Escape Example data.

GET /test/escape

Examples

Example usage:

curl -i http://localhost/escape/text
<b>curl -i http://localhost/escape/html</b>
<xml>curl -i http://localhost/escape/xml</xml>

Success response example

Success response example - Example Response

HTTP/1.1 200 OK {
  field_text: 'text-value',
  field_html: '<b>html-value</b>',
  field_xml: '<xml>xml-value</xml>'
}

Group

Group and Description

Back to top

GET /group/:id

Grouping

Grouping

Back to top

Title and Grouping of param, success and error

GET /test/:id

Parameters - Parameter

Name Type Description
param1 String

No Group, automatically set Group to "Parameter"

Parameters - Replace &#34;login&#34; with this text.

Name Type Description
param2 String

Group "login"
param3 String

Group "login" with default Value

Default value: Default Value

Success response

Success response - 201 - Everything ok, replace &#34;201&#34; with this text.

Name Type Description
success2 String

Group "201"
success3 String

Group "201" with default Value

Default value: Default Value

Success response - Success 200

Name Type Description
success1 String

No Group, automatically set "Success 200"

Error response

Error response - 400

Name Type Description
error2 String

Undefined Group "400"

Error response - 401 - Oh oh, replace &#34;401&#34; with this text

Name Type Description
error3 String

Group "401"

Error response - Error 4xx

Name Type Description
error1 String

No Group automatically set "Error 4xx"

Header

Parameters

Back to top

Test for @apiHeader (same as @apiParam)

GET /header/:id

Headers

Name Type Description
header1 String

Parameter with type and description.
header2 String
header3 String

Parameter with type, description and default value.
header4 String
header5

Basic Parameter with description.
header6
header7

Basic Parameter with description and default value.
header8
header9 optional

Optional basic Parameter with description.
header10 optional
header11 optional

Optional basic Parameter with description and default value.
header12 optional
header13 String optional

Optional Parameter with type and description.
header14 String optional
header15 String optional

Optional Parameter with type, description and default value.
header16 String optional

Header Example

Back to top

Usage of @headerExample.

GET /header/example/

Header examples

An example:

curl -i http://localhost/header/example/

Language

Clojure

Back to top

Test for Clojure Comment-Syntax.

GET /language/clojure

Clojure indented 1

Back to top

GET /language/clojure/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
		  Line 4 indented (with tab at beginning).
	  Line 5 indented.
This is example line 6.

CoffeeScript

Back to top

Test for CoffeeScript Comment-Syntax.

GET /language/coffeescript

CoffeeScript indented 1

Back to top

GET /language/coffeescript/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

CoffeeScript indented 2

Back to top

GET /language/coffeescript/indented2

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Erlang

Back to top

Test for Erlang Comment-Syntax.

GET /language/erlang

Erlang indented 1

Back to top

GET /language/erlang/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
	    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Erlang indented 2

Back to top

GET /language/erlang/indented2

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
Line 4 indented (with tab at beginning).
Line 5 indented.
This is example line 6.

JavaScript

Back to top

Test for JavaScript Comment-Syntax.

GET /language/javascript

JavaScript indented 1

Back to top

GET /language/javascript/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
	    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

JavaScript indented 2

Back to top

GET /language/javascript/indented2

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
	    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Perl

Back to top

Test for Perl Comment-Syntax.

GET /language/perl

Perl indented 1

Back to top

GET /language/perl/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
		Line 4 indented (with tab at beginning).
	Line 5 indented.
This is example line 6.

Perl indented 2

Back to top

GET /language/perl/indented2

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
	    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Perl comment with pod and cut

Back to top

GET /language/perl/podcut

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
        Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Python

Back to top

Test for Python Comment-Syntax.

GET /language/python

Python indented 1

Back to top

GET /language/python/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Python indented 2

Back to top

GET /language/python/indented2

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Ruby

Back to top

Test for Ruby Comment-Syntax.

GET /language/ruby

Ruby indented 1

Back to top

GET /language/ruby/indented1

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
	    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Ruby indented 2

Back to top

GET /language/ruby/indented2

Examples

Test for indented comment.

This is example line 2.
This is example line 3.
	    Line 4 indented (with tab at beginning).
    Line 5 indented.
This is example line 6.

Param

Errors

Back to top

Returned error parameters. Syntax is the same as for @apiParam

GET /param/:id

Error response

Error response - Error 4xx

Name Type Description
error1Error

This is Error 1.
error2Error

This is Error 2.

Parameters

Back to top

Parameters and different Versions: 0.1.1

GET /param/:id

Parameters - Parameter

Name Type Description
param1

Parameter and description.
param2
param3

Parameter, default value and description.

Default value: Default Value
param4 Default value: Default Value
param5 optional

Optional parameter and description.
param6 optional
param7 optional

Optional parameter, default value and description.

Default value: Default Value
param8 optional Default value: Default Value
param9 String

Type, parameter and description.
param10 String
param11 String

Type, parameter and default value.

Default value: Default Value
param12 String Default value: Default Value
param13 String optional

Type, optional parameter and description.
param14 String optional
param15 String optional

Type, optional parameter, default value and description.

Default value: Default Value
param26 String optional Default value: Default Value
param17 String

Type, size, parameter and description.

Size range: 4,8
param18 Number

Type, size, parameter and description.

Size range: 1-3
param19 String

Type, size, parameter, default value and description.

Default value: Default Value
Size range: 4,8
param20 Number

Type, size, parameter, default value and description.

Default value: 1
Size range: 1-3
param21 String

Type, parameter and allowed string value.

Allowed values: "value 1"
param22 String

Type, parameter and allowed list of string values.

Allowed values: "value 1","value 2"
param23 Number

Type, parameter and allowed value.

Allowed values: 4711
param24 Number

Type, parameter and allowed list of values.

Allowed values: 4711,4712
param25 String

Type, size, parameter and allowed string value.

Size range: 1,10
Allowed values: "value 1"
param27 Number

Type, size, parameter and allowed value.

Size range: 1-9999
Allowed values: 4711
param28 Number

Type, size, parameter and allowed list of values.

Size range: 1-9999
Allowed values: 4711,4712
param29 <a href="http://en.wikipedia.org/wiki/Data_type">Custom</a>

Type with markdown link.

Param Example

Back to top

Usage of @apiParamExample.

GET /param/example/

Parameters - Parameter

Name Type Description
name String

Fullname.

Examples

A common example:

curl -i http://localhost/param/example/

Parameters examples

json - A JSON example:

{
  "name": "John Doe"
}

Success

Back to top

Returned success parameters. Syntax is the same as for @apiParam

GET /param/:id

Error response

Error response - Error 4xx

Name Type Description
success1

This is Success 1.
success2

This is Success 2.

Permission

Permission

Back to top

@apiPermission test.

GET /permission/

indent

Trim multi line (spaces)

Back to top

Text line 1 (Begin: 4xSpaces (3 removed)). Text line 2 (Begin: 3xSpaces (3 removed), End: 2xSpaces).

GET /indent/trim/multi/spaces

Trim multi line (tabs)

Back to top

Text line 1 (Begin: 3xTab (2 removed)). Text line 2 (Begin: 2x Tab (2 removed), End: 1xTab).

GET /indent/trim/multi/tabs

Trim multi line (tabs and space)

Back to top

Text line 1 (Begin: 1xTab, 2xSpaces). Text line 2 (Begin: 3xSpaces, End: 1xTab).

GET /indent/trim/multi/tabs/and/space

Trim single line

Back to top

Text line 1 (Begin: 3xSpaces (3 removed), End: 1xSpace).

GET /indent/trim/single

Indent a word

Back to top

text.

GET /indent/word