Skip to content

Latest commit

 

History

History
80 lines (61 loc) · 2.37 KB

README.md

File metadata and controls

80 lines (61 loc) · 2.37 KB

OpenAPI v3 Spec Generator

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