apiSchema - Build api doc blocks from schema

[willfarrell]

Introducing a new concept for building out apidocs using schemas jsonschema (included), xml, etc. These schemas can have apiParams and apiSuccess auto generated. This will reduce errors and keep docs up to date.

Syntax: @apiSchema {SCHEMA_TYPE=PATH_TO_SCHEMA_FILE} [LINE_ARGS_OPTIONAL]

Example

/**
     * @api {get} /api/v1/authenticate/ping Authenticated ping
     * @apiGroup Authentication
     * @apiDescription Can be used to confirm token is still valid.
     *
     * @apiUse MiddlewareAuthentication
     * @apiSchema {jsonschema=./jsonschema/Ping.res.json} apiSuccess
     *
     * @apiSuccessExample data
     *      HTTP/1.1 200 OK
     *      {
     *          "success": true
     *      }
     */

apidoc/apidoc#402

[rottmann]

Nice!

I think i add a better plugin integration, so that your module (and others), can be used easy, without inflate the core.

And the modules itself can be maintaned by the creators (due the lack of my time, it would be a better solution for all) and each module has its own dependencies.

Can you provide your plugin via npm e.g. as apidoc-plugin-schema

Then a user can install

npm install -g apidoc apidoc-plugin-schema

I will add then an automatic load of plugins, whose name start with "apidoc-plugin-".
And add needed hooks in the core.

What did you think?

[willfarrell]

I like the idea of using plugins. Since this plugin hook will be schema based maybe use apidoc-schema-TYPE and have @apiSchema build into the core. When it parses a new type it does a require, loading it in. This will likely require a minimal change from what I've already done. What do you think? I can play around with this over the next week if you like this approach.

[rottmann]

I think we need a simple hook system (array).
Overwriting functions would make it a little bit complicated, especially when i change a function in the core, then all plugins must be updated, so a hook would be easier to maintain.

in apidoc-core/lib/parser.js the code you pulled will be changed, so that it calls a hook line 436

-        elements.push(element);
-
+        if (app.hook['parser-find-elements']) {
+            elements = app.hook['parser-find-elements'](element, filename /* , ...whatever */);
+        } else {
+            elements.push(element);
+        }

So all your schema specific variables and functions (to load the schema) can be in your plugin.

apidoc-core/lib/index.js need only an autoloader for global / local "apidoc-plugin-" dirs, that add parsers, filters, hooks,....

[willfarrell]

Yeah, autoloading into the index would work more cleanly than requiring on the fly.

I'm not sure how we can do it that cleanly with the need for recursion and the ability to pre-parse the plugin-schema line. Or are you thinking about putting the schema parse inside the plugin as well? Maybe something like this.

with @apiSchema in core

// schema autoloaded in index.js
if (self.schema[element.name]) {
    var elementParser = self.parsers[element.name];
             var values = elementParser.parse(element.content, element.source);
             if (self.schemas[values.schema]) {
                var blockExtend = self.schemas[values.schema](values, filename);
                elements = elements.concat(self._findElements(blockExtend, filename));
    }
} else {
    elements.push(element);
}

with @apiSchema in plugin

// schema autoloaded in index.js
if (self.plugin[element.name]) {
                var blockExtend = self.plugin[element.name](element, filename);
                elements = elements.concat(self._findElements(blockExtend, filename));
} else {
    elements.push(element);
}

with this approach the autoloader would need to be recursive to allow a plugin to load sub plugins. ie plugin-schema would then load in plugin-schema-jsonschema. This would also allow people to overwrite existing supported elements which could get interesting. You could then in theory break out the existing element types into plugins themselves.

You're thinking the later approach I'm guessing.

[willfarrell]

Refactor complete. The autoloading will likely need some love, little hacky right now.
I'll submit a new PR for it in a bit.

[rottmann]

Close this for #27

I will change the hook load a little bit to make it more universal and not specific to a plugin name (WordPress Hook Style).