Download the PHP package swisnl/openapi-spec-generator without Composer
On this page you can find all versions of the php package swisnl/openapi-spec-generator. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download swisnl/openapi-spec-generator
More information about swisnl/openapi-spec-generator
Files in swisnl/openapi-spec-generator
Package openapi-spec-generator
Short Description Creates Open API spec for a Laravel JSON:API
License Apache-2.0
Homepage https://github.com/swisnl/openapi-spec-generator
Informations about the package openapi-spec-generator
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
- [x] Generate Schemas/Responses/Request/Errors for all default Laravel JSON:API routes
- [x] 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
- [x] Command to generate to storage folder
- [x] Get basic test suite running with GitHub Actions
- [x] Add extra operation descriptions via config
- [x] Add in tags & x-tagGroups (via config)
- [x] Add tests (Use the dummy by laraveljsonapi to integrate all features)
- [ ] Add custom actions
- [x] Split schemas/requests/responses by action
- [ ] Consider field attributes
- [x] bool readonly
- [x] bool hidden
- [ ] closure based readonly (create/update)
- [ ] closure based hidden
- [x] List sortable fields
- [ ] Fix includes and relations
- [x] Add relationship routes
- [ ] Add includes
- [ ] Add authentication
- [ ] Add custom queries/filters
- [ ] Add a way to document custom actions
- [ ] Tidy up the code!!
- [x] Replace
cebe/php-openapi
withgoldspecdigital/oooas
- [x] 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, glennjacobs and byte-it.
Install
Via Composer
Publish the config file
Usage
Generate the Open API spec
Note that a seeded DB is required! The seeded data will be used to generate Samples.
Descriptions
It's possible to add descriptions to your endpoints by implementing the DescribesEndpoints interface. The added method receives the generated route name as a parameter. This can be used to generate descriptions for all your schema endpoints.
Generating Documentation
Speccy
A quick way to preview your documentation is to use speccy serve
command.
Ensure you have installed Speccy globally and then you can use the following command:
Warning: Seems like Speccy is abandoned (https://github.com/wework/speccy/issues/485).
Laravel Stoplight Elements
Easily publish your API documentation in a local route by using your OpenAPI document in your Laravel Application directly.
For this to work, you have to generate your spec in a public-available location, like the local 'public' disk available in Laravel applications:
After installing it, you should set its url config: STOPLIGHT_OPENAPI_PATH
. For example, if you're using the 'public' disk:
Note: If you need a more dynamic way to get access to the spec URL (for example, in S3 you may need to use temporary URLs), you can publish its Blade template and replace some lines to generate your own URI. Also, you may need to add an Fetch interceptor to integrate it with your authentication methods.
With its default route, ¡you just need to access to your /api/docs
route to preview your specs! :bowtie:
Check its configuration docs for further options.
Standalone Stoplight Elements Web Component
In addition to previous Laravel package, you can use the Stoplight Elements by yourself. It is available as React Component, or Web Component, making it easier for integrating into existing Content Management Systems with their own navigation.
This is useful when you need more advanced customizations in the routing system, integrate it in your existing Vue|React|Vanilla application, or publish it as a non-laravel static HTML site. But... you have to setup it manually. :sweat_smile:
Web component integrated in your Vue application
You can follow the instructions to use the standalone Web Component, grab it into a blade template and armor your view.
It has advanced options, like tryItCredentialPolicy="same-origin"
to use your cookie-based authentication (like Sanctum).
Also, in your Blade view or Vue's app initializer, as this package uses Fetch API you can add interceptors to customize the "try it out" feature, like adding default headers for Content-Type
and/or Accept
to be 'application/vnd.api+json'
to your requests.
Other options
You can check a more exhaustive list of options available at https://openapi.tools/#documentation
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
Contributing
Please see CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
- Glenn Jacobs
- Johannes Kees
- Björn Brala
- Rien van Velzen
- All Contributors
License
Apache License 2.0. All notable changes to the original work can be found in License File for more information.
This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.
SWIS :heart: Open Source
SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.
All versions of openapi-spec-generator with dependencies
goldspecdigital/oooas Version ^2.8
justinrainbow/json-schema Version ^5.2
laravel-json-api/hashids Version ^1.1|^2.0|^3.0
symfony/yaml Version ^5.3|^6.0|^7.0