apidoc-plugin-author

Generates an apiDoc plugin for listing endpoint author.

How to install

As an extension of apiDoc, first install at least apiDoc-core.

This plugin, as with all apiDoc plugins named as apidoc-plugin-*, can be installed locally or globally alongside the apidoc-core. Run either npm install apidoc-plugin-author or npm install -g apidoc-plugin-author.

Getting started

As the author of API endpoints looking for a way to start documentation and actually maintain it, apiDoc is a great way to go. Those who are new to the syntax of apiDoc should thoroughly read the associated documentation. Once familiar with the general syntax, add something similar to the following, to include the author field in the generated documentation.

/**
* @apiAuthor Jason Corns <[email protected]>
**/

The generated api_data.json should now include a block like

{
    "author": "Jason Corns <[email protected]>"
}

Wait, that didn't show up!

apiDoc is the visual wrapper that includes the template for the generated doc site. apiDoc has a dependency on apiDoc-core to generate documentation sites and the apidoc-plugin-author plugin must exist alongside core. In order to add the author field - or any other custom plugin field - the apiDoc template must be updated to include references to the new field.

For example, fork the apiDoc and modify the template-article block to add something like the following:

{{#if article.author}}<h4 class="muted">Authored by: {{article.author}}</h4>{{/if}}

With this modification, and after updating the root project's dependency on apiDoc to the modified fork, a new line will appear below the article title, like

<h4 class="muted">Authored by: Jason Corns &lt;[email protected]&gt;</h4>

Notes and known limitations

• The author field, like all api____ fields, accept the lines containing the @apiAuthor mark and all lines thereafter up to either: another api____ mark, or: the end of the comment block. The content includes the newline mark(s) as a consolidated string. Issue #4 will cover this case.
• The author field is, for now, a singular field. Multiple author listings will show only a single value, as a "last-in-wins" value.