Generating an OpenAPI spec

[brayniverse]

Hello 👋,

I have been manually creating a JSON:API implementation and while I think we've been doing a good job there has been mistakes along the way. When looking at this package I reckon we wouldn't have made as many if we were using json-api-server. I have been experimenting with the package and it seems really good.

All this is to say, I'm still new to the package and forgive me if this has already been asked. As far as I could tell, there hasn't been a discussion on it yet.

Is it possible to generate an OpenAPI spec file from the schema you define as part of json-api-server? It seems like all the information to generate one is available. If it is not currently possible, would you consider including it as part of the core package if I were to help implement it?

Thank you,

Chris

[tobyzerner]

Hey Chris, thank you for the kind words 😊

You're right that this hasn't been talked about before, but it's always been in the back of my mind as something that would be possible and desirable.

In a couple months I'm starting a new job that will allow me to invest a lot more time into this package, and I'd love to look at it then. In the meantime, any start you can make would be great!

[brayniverse]

@tobyzerner congratulations on the new job. I'll see what I can do.

[tobyzerner]

With the release of v1.0.0-alpha.1, which adds support for typed attributes, consider work on OpenAPI definition generation well underway :)

[bertramakers]

Hi @tobyzerner, is there any news regarding the OpenAPI spec support?

[tobyzerner]

Hi @bertramakers, work is in progress (but incomplete) on the openapi branch. Feel free to try it out and let me know what you think!

use Tobyz\JsonApiServer\OpenApi\OpenApiGenerator;

$api = new JsonApi();

// $api->resource(...) etc

$generator = new OpenApiGenerator();

print_r($generator->generate($api)); // or encode as json, yaml

[bertramakers]

Thanks, I'll try it out soon!

One small suggestion I already have would be to put the name of the collection in the summary of the operation instead of the tags: main...openapi#diff-03e5541a3e5fe9ec77d2c71f17861fe6c28554322af2fd5cd0f6dd5b2daa3fe7R188

See definition of summary in operation objects here: https://swagger.io/specification/#operation-object

Edit: Disregard this, it makes sense to put $collection->name() in tags because it's usually the type of the resource and not the name of the operation. It would be nice to be able to set a name/summary on the endpoint though but that's nice to have.

[joshmurrayeu]

Hi folks.

I've just about to rewrite an application that has gotten tricky to work with due to technical debt + some horrible abstractions. I've used this package (and branch [openapi]) for a proof-of-concept and it looks to be working pretty well.
I'd be happy to pick up some of the OpenAPI generation work over the next few weeks as it's something that I'll need going forward.

Some of the pieces I'd likely look into are:

• Atomic extension isn't output to the OpenAPI spec
• Ability to change the specification info tag (e.g. name, description, documentation URLs etc.)
• Clean up the components that are built
• As @bertramakers mentions above, some nicer tag information

I do need some advice on one aspect, @tobyzerner, and that is Laravel commands. Here's a short example:

<?php

namespace App\JsonApi\Console\Commands;

use App\JsonApi\AdminJsonApi;
use Illuminate\Console\Command;
use Illuminate\Filesystem\FilesystemManager;
use Symfony\Component\Console\Command\Command as SymfonyCommand;
use Tobyz\JsonApiServer\OpenApi\OpenApiGenerator;

class GenerateOpenApiCommand extends Command
{
    protected $name = 'json-api:open-api:generate';

    public function handle(AdminJsonApi $adminJsonApi, FilesystemManager $filesystemManager): int
    {
        $generator = new OpenApiGenerator();

        $contents = json_encode($generator->generate($adminJsonApi));

        $filesystemManager->disk('local')->put('openapi/spec.json', $contents);

        $this->info('Done');

        return SymfonyCommand::SUCCESS;
    }
}

Should Laravel commands be included in this repository or a separate "Laravel bridge"? Let me know your views.