API documentation

Mapbender3 offers an API documentation at http://api.mapbender3.org/.

The API documentation is shipped with Mapbender and can be created with:

bin/composer docs

The documentation is then available at: http://localhost:8000/docs/api/ and the Mapbender-documentation at: http://localhost:8000/docs/

Please see the Contributing Guide for details on using the built-in server.

For usage in Apache or Nginx, you may have to adjust the access-rights for the generated files in the web-directory of Mapbender.

How to write Mapbender3 API Documentation?

PHP

ApiGen is used to generate API documentation. ‘All’ you have to do is to insert docblocks in your code. Below you find an example class with docbblock annotations:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
<?php

/**
 * License Block - Todo
 */

namespace Mapbender;

use Mapbender\Component\Foo;

/**
 * Just an API-doc example (Oneline description used in lists)
 *
 * Bar is just an API documentation example to serve as a guideline,
 * inspiration and to be included in the developer's book.
 *
 * This file is directly included in the documentation. Yeah!
 *
 * @todo Make me better
 *
 * @author Christian Wygoda <christian.wygoda@wheregroup.com>
 */
class Example extends Foo
{
    /**
     * Constructor
     *
     * Does some magic.
     */
    public function __construct()
    {
    }

    /**
     * Magic function
     *
     * Does some pretty awesome magic.
     *
     * @param array $input input data
     * @return string Result string
     *
     * @deprecated use newMagic instead
     */
    public function oldMagic(array $input)
    {
    }

    /**
     * Magic function
     *
     * Does some pretty awesome magic, only better.
     *
     * @param array $input input data
     * @return string Result string
     *
     * @todo make faster
     */
    public function newMagic(array $input)
    {
    }
}

Have a look at the docblocks at Example.php.

JavaScript

This has not yet been decided as good tools are almost not to be found.