NAME

Text::API::Blueprint - Markdown generator for API blueprint format

VERSION

version 0.003

FUNCTIONS

Compile

Compile({
    # Meta
    host => 'hostname',
    # Intro
    name => 'title',
    description => 'short introduction',
    resources => [
        # Resource
        {
            ...
        }
    ],
    groups => [
        # Group
        name => [
            # Resource
            {
                ...
            }
        ]
    ],
});

Section

Section(sub {
    ...
})

Invokation: Section( CodeRef $coderef, [ Int $offset = 1 ])

Increments header offset by $offset for everything executed in $coderef.

Intro

Intro('Our API');
Intro('Our API', 'With a short introduction');

Invokation: Intro(Str $name, [ Str $description ])

# $name
$description

Concat

Concat('foo', 'bar');

Invokation: Concat( Str @blocks )

$block[0]

$block[1]

$block[2]

...

Text

Text('foo', 'bar');

Invokation: Text( Str @strings )

$string[0]
$string[1]
$string[2]
...

Code

Code('foobar');
Code('{"foo":"bar"}', 'json');

Invokation: Code(Str $code, [ Str $lang = '' ])

```$lang
$code
```

Group

Group('header', 'body');
Group('name', [
    # Resource
    {
        ...
    }
]);

Invokation: Group(Str $identifier, Str|ArrayRef[HashRef|Str] $body)

If $body is an ArrayRef, every item which is a HashRef will be passed to "Resource".

# Group $identifier

$body

Resource

Resource({
    ...
});

Invokation: Resource(HashRef $args)

Allowed keywords for $args:

method, uri, identifier

With method and uri
```
## $method $uri

$body
```
With identifier and $uri
```
## $identifier [$uri]

$body
```
With uri
```
## $uri

$body
```
Other combinations are invalid.
body

If body isa CodeRef, see "Section". description, parameters, attributes, model, actions are not allowed then.
description

A short introduction as a single string.
parameters

See "Parameters".
attributes

See "Attributes".
model

See "Model".
actions

Isa ArrayRef.

See "Action".

Model

Model({
    type => 'mime/type',
    # Payload
    ...
});
Model('mime/type', 'payload');

Invokation: Model(Str $media_type, Str|HashRef $payload, [ Int $indent ]);

See "Payload" if the first and only argument is a HashRef.

+ Model ($media_type)

$payload

Schema

Schema('body');

Invokation: Schema(Str $body, [ Int $indent ])

+ Schema

$body

Attribute

Attribute('scalar', {
    type => 'string',
    example => 'foobar',
    description => 'a text',
});
Attribute('list', {
    enum => 'number',
    example => 3,
    description => 'a number from 1 to 5',
    members => [1,2,3,4,5],
});
Attribute('hash' => [
    foo => {
        type => 'string',
        ...
    },
    bar => {
        ...
    }
]);

Attributes

Attributes('reference');
Attributes([
    # Attribute
    name => {
        ...
    }
]);

Action

Action({
    ...
});

Invokation: Action(HashRef $args)

Allowed keywords for $args:

identifier, method, uri

With $identifier $method and $uri:
```
### $identifier [$method $uri]

$body
```
With $identifier and $method:
```
### $identifier [$method]

$body
```
With $method:
```
### $method

$body
```
Other combinations are invalid.
description
relation

See "Relation".
parameters

See "Parameters".
attributes

See "Attributes".
assets

Isa ArrayRef interpreted as a key/value paired associative list.

The key is splited into two parts by the first whitespace, named keyword and id.

If the value isa string, "Reference" is called with <<(keyword, id, value)>>

If the value is anything else, "Asset" is called with <<(keyword, id, value)>>
requests

See "Request_Ref" if the value isa string. See "Request" otherwise.
responses

See "Response_Ref" if the value isa string. See "Response" otherwise.

Payload

Payload({
    ...
});

Invokation: Payload(HashRef $args)

Allowed keywords for $args:

description

A short introduction as a single string.
headers

See "Headers".
attributes

See "Attributes".
body

See "Body".
code, lang

See "Bode_CODE".
yaml

See "Body_YAML".
json

See "Body_JSON".
schema

See "Schema".

Asset

Asset('Request', 'foo', {
    type => 'mime/type',
    # Payload
    ...
});

Invokation: Asset( Str $keyword, Str $identifier, HashRef $payload )

See "Payload" for %payload

# $keyword $identifier ($type)

$payload

Reference

Reference('Request', 'foo', 'bar');
Reference('Response', 'foo', 'bar');

Invokation: Reference(Str $keyword, Str $identifier, Str $reference)

# $keyword $identifier

    [$reference][]

Request

Request('foo', { ... });

Invokation: Request(@args)

Calls "Asset"( 'Request', @args )

Request_Ref

Request_Ref('foo', 'bar');

Invokation: Request_Ref(@args)

Calls "Reference"( 'Request', @args )

Response

Response('foo', { ... });

Invokation: Response( @args )

Calls "Asset"( 'Response', @args )

Response_Ref

Response_Ref('foo', 'bar');

Invokation: Response_Ref(@args)

Calls "Reference"( 'Response', @args )

Parameters

Parameters([
    foo => {
        # Parameter
        ...
    },
    bar => {
        # Parameter
        ...
    }
]);

Invokation: Parameters(ArrayRef[Str|HashRef] $parameters)

For every keypair in @$parameters "Parameter"($key, $value) will be called

Parameter

Parameter('foo', {
    example => 'foobar',
    required => 1,
    type => 'string',
    shortdesc => 'a string',
    longdesc => 'this is a string',
    default => 'none',
});
Parameter('foo', {
    example => '3',
    required => 0,
    enum => 'number',
    shortdesc => 'an optional number',
    longdesc => 'an integer between 1 and 5 (both inclusive)',
    default => 1,
    members => [1,2,3,4,5],
});

Invokation: Parameter( Str $name, HashRef $args )

+ $name: `$example` ($type, $required_or_optional) - $shortdesc

    $longdesc

    + Default: `$default`

    + Members
        + `$key` - $value
        + ...

Headers

Headers([
    FooBar => '...', # Foo-Bar
    -foof  => '...', # X-Foof
]);

Invokation: Headers(ArrayRef[Str] $headers)

The headers are encoded and prettified in a fancy way. See HTTP::Headers::Fancy for more information.

Body

Body('foobar');

Invokation: Body( Str $body )

+ Body

        $body

Body_CODE

Body_CODE('foobar');
Body_CODE('foo', 'bar');

Invokation: Body_CODE( Str $code, Str $lang )

+ Body

    ```$lang
    $code
    ```

Body_YAML

Body_YAML({ ... });
Body_YAML([ ... ]);

Invokation: Body_YAML( HashRef|ArrayRef $struct )

+ Body

    ```yaml
    $struct
    ```

Body_JSON

Body_JSON({ ... });
Body_JSON([ ... ]);

Invokation: Body_JSON( HashRef|ArrayRef $struct )

+ Body

    ```json
    $struct
    ```

Relation

Relation('foo');

Invokation: Relation( Str $link )

+ Relation: $link

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libtext-api-blueprint-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The ISC License

To install Text::API::Blueprint, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Text::API::Blueprint

CPAN shell

perl -MCPAN -e shell
install Text::API::Blueprint

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

FUNCTIONS

Compile

Section

Meta

Intro

Concat

Text

Code

Group

Resource

Model

Schema

Attribute

Attributes

Action

Payload

Asset

Reference

Request

Request_Ref

Response

Response_Ref

Parameters

Parameter

Headers

Body

Body_CODE

Body_YAML

Body_JSON

Relation

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions