byteit/openapi-spec-generator

Creates Open API spec for a Laravel JSON:API

0.3.0 2021-08-10 07:09 UTC

Requires

• php: >=7.4|^8.0
• goldspecdigital/oooas: ^2.8
• justinrainbow/json-schema: ^5.2
• laravel-json-api/hashids: ^1.0@beta
• symfony/yaml: ^5.3

Requires (Dev)

• ext-json: *
• laravel-json-api/laravel: ^1.0
• orchestra/testbench: ^6.9
• phpunit/phpunit: ^9.5

Apache-2.0

• Glenn Jacobs
• Johannes Kees

README

Designed to work with Laravel JSON:API

!!! Disclaimer: this project is work in progress and likely contains many bugs, etc !!!

What it can and can't

Can

• Generate Schemas/Responses/Request/Errors for all default Laravel JSON:API routes
• Use a seeded database to generate examples

Can't yet

• Customisation of the generation
• Generation for custom actions
• Generation for custom filters
• Generation for anything custom
• Generation for MorphTo relations (MorphToMany works)
• Generation of Pagination Meta
• Generation of Includes
• Generation of Authentication/Authorization

TODO

• Command to generate to storage folder
• Get basic test suite running with GitHub Actions
• Add extra operation descriptions via config
• Add in tags & x-tagGroups (via config)
• Add tests (Use the dummy by laraveljsonapi to integrate all features)
• Add custom actions
• Split schemas/requests/responses by action
• Consider field attributes
  • bool readonly
  • bool hidden
  • closure based readonly (create/update)
  • closure based hidden
• List sortable fields
• Fix includes and relations
  • Add relationship routes
  • Add includes
• Add authentication
• Add custom queries/filters
• Add a way to document custom actions
• Tidy up the code!!
• Replace cebe/php-openapi with goldspecdigital/oooas
• Move to an architecture inspired by vyuldashev/laravel-openapi
• Use php8 attributes on actions/classes to generate custom docs

🙏 Based upon initial prototype by martianatwork and glennjacobs

Usage

Install package

composer require byteit/openapi-spec-generator

Publish the config file

php artisan vendor:publish --provider="LaravelJsonApi\OpenApiSpec\OpenApiServiceProvider"

Generate the Open API spec

php artisan jsonapi:openapi:generate v1

Note that a seeded DB is required! The seeded data will be used to generate Samples.

Generating Documentation

A quick way to preview your documentation is to use Speccy. Ensure you have installed Speccy globally and then you can use the following command.

speccy serve storage/app/v1_openapi.yaml