Laravel-apidoc-generator: Plans for the next major release

[shalvah]

Technical requirements:

PHP 7.2+
Laravel 5.8+

Projected release date

Mid-November 2019

Features

Different documentation templates/ability to customise them

We're going to look at VuePress - see https://github.com/mpociot/laravel-apidoc-generator/issues/476#issuecomment-493877996
Related issues: #563

Update: We won't be doing this at this time. I did a PoC for VuePress, and it turns out "support" simply means adjusting the template view used a bit, which any end user can do themselves. The payoff is not worth adding the extra baggage to this package.

@queryParam and @bodyParam array/object support (✔ in #597)

Related issues: #514 #424 #397
Related PR: #535

Support for Eloquent resources (✔ in #601)

Related issue: #375

Provide options for non-static docs (✔ in #608)

Related issue: #373

Replace bindings with @urlParam annotation (✔ in #599)

bindings is confusing, urlParam is clearer.
Related PR: #531

Update dependencies (✔)

Testbench, PHPUnit, DIngo

Exploring

Consolidate options for specifying headers.

Currently we have routes.*.apply.response_calls.headers and routes.*.apply.headers? Should we replace one with the other? Should we ditch both and go with a @header?

Improvements to the plugin API

A major consideration here: how can we pass configuration to the strategies? (for instance, the config that currently goes into response_calls)

[warlord0]

I'm new to this, but finding it very useful. There are a few issues I'd like to see covered though.

__JWT Auth__
Rather than add the token into the --header arg (which I can't get working). Authenticate before documenting and use the supplied header token in the "Authorization": "Bearer {token}" for calls where they are labelled @authenticated.

__@authenticated__
Only add the Authorization header to the examples if they are labelled @authenticated. Currently you have to create separate groups for routes you want in include/exclude to give different headers to.

[shalvah]

JWT Auth - Have you seen the docs? There's no --header flag. Whatever headers you configure in the response_calls section are sent along in response calls.

Your second point makes sense. Worth considering.

I think we may also add a "name" property for route groups. It won't be used for anything, but it can help people distinguish between their rulesets ("this is v1routes, this is v2routes").

[donovanhare]

@shalvah any chance the @QueryParam and @bodyParam array/object support issues could be rectified in a minor release as opposed to a major?

[shalvah]

@shalvah any chance the @QueryParam and @bodyParam array/object support issues could be rectified in a minor release as opposed to a major?

@donovanhare I doubt it. There's likely to be bugs after release, and it would be a lot of stress on me to backport the fixes to multiple versions at the same time.

[shalvah]

4.0.0 is out!🎉

Thanks for the help, everyone!