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

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