dingo/blueprint

Generate valid API Blueprint documentation

blueprint's Issues

Add schema section

The schema section can be used by Dredd to test the results primitive types.

For more information about schema testing see Gavel which is used by Dredd:
http://www.relishapp.com/apiary/gavel/v/0-1/docs/data-validators-and-output-format#json-schema-validator

Resource Group Versions

Is it possible to hide a specific resource group from version documentation? We have some private routes which we placed under a specific version. The routes itself don't show up on the documentation, but the resource group itself does. Is it possible to hide this as well?

Support PHP8?

Arrays in parameters

We have some cases where we have to use arrays as parameters in our API, however it seems these parameters are being discarded when the documentation is being generated.

This is what I have tried so far.

@Parameter("attachment[n][filename]", type="string", description="Attachment filename."),
@Parameter("attachment[n][contents]", type="string", description="Base64-encoded file contents."),

Is there any way to include this in the generated documentation?

Resource parameters

@jasonlewis Just a quick question for clarification.

Currently you can define resource parameters and they get added to the resource list of parameters, but they won't get added to parameter list defined on method be it route or query parameter. E.g.

# Order [/user/{user_id}/order]
foo bar baz

+ Parameters
    + client_id (integer, required) - Client's ID

## List all orders [GET /user/{user_id}/order{?limit,offset}]
foo bar baz

+ Parameters
    + limit (integer, optional) - foo
    + offset (integer, optional) - bar

But since user_id won't get added to parameters defined for the method it will be impossible to make test requests from Apiary console, because I can not add the required parameter to the request. Since I don't know any other tools, I am taking strictly about Apiary here.

If this isn't the case then please correct me, but just in case my thinking is correct I have a PR ready.

Preventing Laravel 5.2 from installing

Cannot upgrade to Laravel 5.2 beta as dingo blueprint requires 5.1.*

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - dingo/api 1.0.x-dev requires dingo/blueprint 0.1.* -> satisfiable by dingo/blueprint[v0.1.3, v0.1.0, v0.1.1, v0.1.2].
    - dingo/api 1.0.x-dev requires dingo/blueprint 0.1.* -> satisfiable by dingo/blueprint[v0.1.3, v0.1.0, v0.1.1, v0.1.2].
    - dingo/blueprint v0.1.3 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - dingo/blueprint v0.1.0 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - dingo/blueprint v0.1.1 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - dingo/blueprint v0.1.2 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - dingo/blueprint v0.1.3 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - dingo/api v1.0.0-beta1 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - dingo/api v1.0.0-beta2 requires illuminate/support 5.1.* -> satisfiable by laravel/framework[v5.1.26], illuminate/support[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.6, v5.1.8].
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.1
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.13
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.16
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.2
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.20
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.22
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.25
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.6
    - don't install laravel/framework v5.2.0-beta1|don't install illuminate/support v5.1.8
    - Can only install one of: laravel/framework[v5.2.0-beta1, v5.1.26].
    - Installation request for laravel/framework 5.2.* -> satisfiable by laravel/framework[v5.2.0-beta1].
    - Installation request for dingo/api 1.0.x@dev -> satisfiable by dingo/api[1.0.x-dev, v1.0.0-beta1, v1.0.0-beta2].

Syntax Error

https://github.com/dingo/blueprint/blob/master/src/Blueprint.php#L408

should be $this->includePath

Why this package doesn't support L5.5, 5.6

It's been months since Laravel 5.5 is released and recently L5.6 is released while this package still doesn't support illuminate/filesystem 5.5 or 5.6?
I don't know if upgrading from 5.4 to 5.6 requires special consideration, but the act of not updating version number over months gives me the sense of either this project is not actively maintained or maintainers don't care if this package can't be installed on newer versions of Laravel.
What makes this problem worse it that dingo/API requires this package by default.
So my question is the reason to delay this much for updating this dependency? Do they don't have enough time to maintain this repo, or they don't care about newer versions or they use other libs for API developing on Laravel?!

Support for standalone sections outside of classes

I was wondering if there is a way to add Blueprint sections like an introduction or other support information such as a place to show a table of error codes, for example.

Blueprint is generating the same documentation multiple times

@jasonlewis For some reason the blueprint package is generating the documentation for one of my controllers 9 times and another one of my controllers 4 times.

I only have these two controllers documented so far, however I have several more controllers to do. Any idea why this could be happening?

@Attributes is not parsed into the bluprint doc

@jasonlewis The "@Attributes" is not parsed into the blueprint documentation upon generation.

I've used the example from the blueprint/tests/Stubs/UserPhotosResourceStub.php

Anyway to solve it? Thanks

Response body with array

I have some issues when trying to generate the docs, when my responsebody contains a more complex JSON string. This works:

@Response(200, body={"instancetypes":{"id":3,"name":"Wand"}})

but:

@Response(200, body={"instancetypes":{"id":3,"name":"Wand", "children":[{"id":1}]}})

throws the following exception:
[Doctrine\Common\Annotations\AnnotationException]
[Syntax Error] Expected PlainValue, got '[' at position 131 in method App\Http\Controllers\ElementTypeController::showAllSubtypes().

Is there a contradiction?

dingo/api version

laravel 5.5 use phpdocumentor/reflection-docblock is 5 version

so blueprint v2.x-dev

but illuminate/filesystem: ^7.0|^8.0
illuminate/support: ^7.0|^8.0

Support multiple responses

I tried using:

/**
 * @Response(200, body={"obj": {}})
 * @Response(404, body={"error": "not found"})
 */

But only the first response shows up. Note that I am using pure Laravel (I adapted the artisan command), so that may be the issue potentially.

This is an awesome project btw!

Use AnnotationReader instead of SimpleAnnotationReader

Hello i wanted to ask you why don't you use AnnotationReader instead of SimpleAnnotationReader. If you will use AnnotationReader you can do this:

use Dingo\Blueprint\Annotation as BP;
use Dingo\Blueprint\Annotation\Method as BPM;

/**
 * @BP\Resource("Test")
 */
class TestController extends Controller
{
    /**
     * Ask for new service
     *
     * @BPM\Get("/test")
     * @BP\Versions({"v1"})
     */
     public function test(){
     }
}

And you can also remove this ugly code from your registerAnnotationLoader() function:

$this->reader->addNamespace('Dingo\\Blueprint\\Annotation');
$this->reader->addNamespace('Dingo\\Blueprint\\Annotation\\Method');

Add HOST to API blueprint from API_DOMAIN

For apiary.io console tests it is required to fill the HOST variable with the API URL
As this is already defined in API_DOMAIN I think it would be useful for everyone using the doc feature

Thank you.

How to use this without dingo/api?

Sorry for the stupid question, but I've pulled this into my Laravel application and I have no idea how to use it independently of the larger api package. Any information on how to get up and running would be really helpful and thank you!

Matt

Laravel 5.3 error (not sure if related or not)

Hello,

I am running Laravel 5.3 and I keep getting an error when I run api:docs I tracked it down to the line

protected function getAnnotationByType($type)
{
    return array_first($this->annotations, function ($key, $annotation) use ($type) {
        $type = sprintf('Dingo\\Blueprint\\Annotation\\%s', $type);

        return $annotation instanceof $type;
    });
}

If I change the return $annotation instanceof $type; to return $key instanceof $type; it works perfectly fine, but for me on PHP 7 Laravel 5.3 $annotation is equal to a 0 or 1.

Not sure exactly what is up.

How can I represent `array[object]` attributes?

I want to write blueprint document like below.

+ Request (application/json)

    + Attributes
        + api_token: 1 (number, optional) - The photo id
        + adds (array[object])
            + (object)
                + `a` (string) - adds a
                + `b` (string) - adds b
            
    + Body

            {
                "api_token": "123",
                "adds": [
                    {
                        "a" : "beijing",
                        "b" : "Tian’anmen"
                    }
                ]
            }

How do I write this structure of dingo/blueprint?

Ability to generate per controller

Currently generating docs for my API, im noticing its turning into a really big API and the docs MD file is growing insanely fast.

Is there a way we can generate docs per controller? Like following:

api:docs --name News --output-file="api-news.md" --use-controller="NewsController"

Incompatible with Laravel 5.5

Currently the illuminate/support and illuminate/filesystem dependencies only go to 5.4.* and prevent the package from being used in a Laravel 5.5 project

I don't think there were any major changes to these components in 5.5.* but I haven't taken a close look yet.

Incompatible with Phpdocumentor Reflection-Dockblock 3.2.1

I'm getting below exception on installing Dingo/Api package on Laravel 5.4 which I resolved installing by 3.1.* version of reflection-dockblock package.

Problem 1
- Conclusion: don't install dingo/api 1.0.x-dev
- Conclusion: don't install dingo/api v1.0.0-beta8
- Conclusion: don't install dingo/api v1.0.0-beta7
- Conclusion: don't install dingo/api v1.0.0-beta6
- Conclusion: don't install dingo/api v1.0.0-beta5
- Conclusion: don't install dingo/api v1.0.0-beta4
- Conclusion: don't install dingo/api v1.0.0-beta3
- Conclusion: don't install dingo/api v1.0.0-beta2
- Conclusion: remove laravel/framework v5.4.32
- Installation request for phpdocumentor/reflection-docblock (locked at 3.2.1) -> satisfiable by phpdocumentor/reflection-docblock[3.2.1].
- Installation request for dingo/api 1.0.x@dev -> satisfiable by dingo/api[1.0.x-dev, v1.0.0-beta1, v1.0.0-beta2, v1.0.0-beta3, v1.0.0-beta4, v1.0.0-beta5, v1.0.0-beta6, v1.0.0-beta7, v1.0.0-beta8].
- Conclusion: don't install laravel/framework v5.4.32
- dingo/api v1.0.0-beta1 requires illuminate/routing 5.1.* -> satisfiable by illuminate/routing[v5.1.1, v5.1.13, v5.1.16, v5.1.2, v5.1.20, v5.1.22, v5.1.25, v5.1.28, v5.1.30, v5.1.31, v5.1.41, v5.1.6, v5.1.8].
- don't install illuminate/routing v5.1.1|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.13|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.16|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.2|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.20|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.22|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.25|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.28|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.30|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.31|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.41|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.6|don't install laravel/framework v5.4.32
- don't install illuminate/routing v5.1.8|don't install laravel/framework v5.4.32
- Installation request for laravel/framework (locked at v5.4.32, required as 5.4.*) -> satisfiable by laravel/framework[v5.4.32].

Laravel 5.4

I'm having issues installing the API package because this repo doesn't support Laravel 5.4. Any chance we can get a version that does?

Able to set URI Parameter 'example_value' ?

Hi,

I'm wondering if it's possible to set the example_value documented here.

I have looked through the test stubs here and the wiki docs on dingo/api but I'm coming up empty.

How do you guys adding overview section?

I'm working on an API service, which have some endpoints are handled by third-party libraries(e.g: Laravel Passport) and have a general error format that should be output to the final blueprint document.

I want to place an overview section before main content like this:
https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-api-name-section

Sadly, it seems not supported by dingo/blueprint, so I create a new controller, define several empty methods to output these documents.

Is there anyway that I can insert contents as overview section into the blueprint document?

Invalid tag v3.0.1

It seems one of releases was tagged as 3.0.1 - https://github.com/dingo/blueprint/releases/tag/v3.0.1 and now Packagist shows v3.0.1 as latest version https://packagist.org/packages/dingo/blueprint what causes also invalid info for composer outdated command:

composer outdated
dingo/blueprint            v0.4.2 v3.0.1 API Blueprint documentation generator.

A spell miss in blueprint/src/Blueprint.php?

https://github.com/dingo/blueprint/blob/master/src/Blueprint.php#L251

if (! empty($request->headers)) {
    $this->appendHeaders($contents, $request->headers);
}

I think the write way is

if (! empty($response->headers)) {
    $this->appendHeaders($contents, $response->headers);
}

Artisan command

Is there an artisan command to generate blueprints? If no, how can one generate blueprints?

Resource is a (soft) reserved word as of PHP 7.0

As of PHP 7.0 resource is a reserved word.

Can we change the class name to a non reserved word? Ie, Resource becomes RestResource?