Skip to content

example.md

Latest commit

 

History

History
1255 lines (889 loc) · 30.1 KB

example.md

File metadata and controls

1255 lines (889 loc) · 30.1 KB

test v0.13.0

RESTful web API Documentation Generator

Header .md File

This is the content of the header.md file.

Table of contents

this quote is prepended to this doc using a file prepend.md

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

Back to top

This is a simple deprecated hint.

GET /deprecated/foo/:id

Parameters - Parameter

Name Type Description
param1

Parameter and description.

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.

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>'
}

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.');

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

Header Example

Back to top

Usage of @headerExample.

GET /header/example/

Header examples

An example:

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

Parameters

Back to top

Test for @apiHeader (same as @apiParam)

GET /header/:id

Headers - Header

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

Headers - Request headers

Name Type Description
reqHeader1

Basic Parameter with description.
reqHeader2

Basic Parameter with description.

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 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.

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.

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.

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.

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.

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"
}

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

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

Indent a word

Back to top

text.

GET /indent/word

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 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 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 single line

Back to top

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

GET /indent/trim/single

Category_official

Delete a category

Back to top

Delete a category. Sample request has been disabled here.

DELETE /category

Query Parameters

Name Type Description
id Number

Category ID.

Parameters examples

json - Some json code:

{
  "user": "Sample User",
   "payload": {
     "test": [
       "code": "
         public class HelloWorldTest {
           HelloWorld hw = new HelloWorld();
           @Test
           public void testOkay {
           assertEquals(\"HelloWorld\", hw.getMsg());
         }
      }"
     ]
   }
}

Get a category

Back to top

Get a category. Sample request on example.com here.

GET /category

Query Parameters

Name Type Description
id Number optional

Category ID.

Default value: 123
id2 Number

Category ID2.

City

Create a new city

Back to top

Create a new city.

POST /city

Query Parameters

Name Type Description
view String

Type of view.

Default value: Aerial
Allowed values: Aerial,Land,Underwater
zoom Number

Zoom.

Request Body

Name Type Description
name String

Name of the city

Default value: Paris

User

Change a User

Back to top

This function has same errors like POST /user, but errors not defined again, they were included with "apiErrorStructure"

PUT /user/:id

Parameters - Parameter

Name Type Description
id Number

id of the user.

Request Body

Name Type Description
name String

Name of the User.
avatar File

Upload avatar.

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNameTooShort

Minimum of 5 characters required.

Error response example

Error response example - Response (example):

HTTP/1.1 400 Bad Request
{
  "error": "UserNameTooShort"
}

Create a new User

Back to top

In this case "apiErrorStructure" is defined and used. Define blocks with params that will be used in several functions, so you dont have to rewrite them.

POST /user

Request Body

Name Type Description
age Number

Age of the User
name String

Name of the User

Default value: Caroline
extraInfo.hireDate Date

Date when user was hired
extraInfo.hireDateWithDefault Date

Date when user was hired with default

Default value: 2021-09-01
extraInfo.nickname String

Nickname of the user
extraInfo.isVegan Boolean

Is the user vegan? (boolean with default)

Default value: true
extraInfo.isAlive Boolean

Is the user alive? (boolean with no default)
extraInfo.secrets.crush String

The user secret crush
extraInfo.secrets.hair Number

Number of hair of user

Default value: 1000

Success response

Success response - Success 200

Name Type Description
id Number

The new Users-ID.

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNameTooShort

Minimum of 5 characters required.

Error response example

Error response example - Response (example):

HTTP/1.1 400 Bad Request
{
  "error": "UserNameTooShort"
}

Delete user

Back to top

Be careful! This will remove all the data associated with that user!

DELETE /user/:id

Headers - Header

Name Type Description
Authorization String

The token can be generated from your user profile.

Header examples

Header-Example

"Authorization: token 5f048fe"

Parameters - Parameter

Name Type Description
id Number

id of the user.

Examples

Curl example

curl -X DELETE -H "Authorization: token 5f048fe" -i https://api.example.com/user/4711

Javascript example

const client = AcmeCorpApi('5f048fe');
const user = client.deleteUser(42);

Python example

client = AcmeCorpApi.Client(token="5f048fe")
user = client.delete_user(42)

Success response

Success response - Success 200

Name Type Description
result String

ok if everything went fine.
nullableField String optional

This response field is not always there (can be null).

Success response example

Success response example - Success-Example

HTTP/1.1 200 OK
{
    "result": "ok"
}

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNotFound

The id of the User was not found.

Error response - 500 Internal Server Error

Name Type Description
InternalServerError

The server encountered an internal error.

Error response example

Error response example - Response (example):

HTTP/1.1 401 Not Authenticated
{
  "error": "NoAccessRight"
}

Read data of a User

Back to top

Compare version 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.

GET /user/:region/:id/:opt

Headers - Header

Name Type Description
Authorization String

The token can be generated from your user profile.
X-Apidoc-Cool-Factor String

Some other header with a default value.

Header examples

Header-Example

"Authorization: token 5f048fe"

Parameters - Parameter

Name Type Description
id Number

User unique ID
region String

User region

Default value: fr-par
opt String optional

An optional param

Examples

Curl example

curl -H "Authorization: token 5f048fe" -i https://api.example.com/user/fr-par/4711
curl -H "Authorization: token 5f048fe" -H "X-Apidoc-Cool-Factor: superbig" -i https://api.example.com/user/de-ber/1337/yep

Javascript example

const client = AcmeCorpApi('5f048fe');
const user = client.getUser(42);

Python example

client = AcmeCorpApi.Client(token="5f048fe")
user = client.get_user(42)

Success response

Success response - Success 200

Name Type Description
id Number

The Users-ID.
registered Date

Registration Date.
name String

Fullname of the User.
nicknames String[]

List of Users nicknames (Array of Strings).
profile Object

Profile data (example for an Object)
profile.age Number

Users age.
profile.image String

Avatar-Image.
options Object[]

List of Users options (Array of Objects).
options.name String

Option Name.
options.value String

Option Value.

Error response

Error response - Error 4xx

Name Type Description
NoAccessRight

Only authenticated Admins can access the data.
UserNotFound

The id of the User was not found.

Error response - 500 Internal Server Error

Name Type Description
InternalServerError

The server encountered an internal error

Error response example

Error response example - Response (example):

HTTP/1.1 401 Not Authenticated
{
  "error": "NoAccessRight"
}

Thank a user: this is quite a long name indeed

Back to top

This is here to have a long name in the left menu.

POST /user/:id

Footer .md File

This is the content of the footer.md file.