Download the PHP package arkitechdev/openapi without Composer
On this page you can find all versions of the php package arkitechdev/openapi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download arkitechdev/openapi
More information about arkitechdev/openapi
Files in arkitechdev/openapi
Package openapi
Short Description A package for creating OpenAPI 3 specification files.
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package openapi
OpenApi docs generator
Requirements
- PHP 7.3 | PHP 8.0
- Laravel 8 (if you want to use the facade and command)
Installation
Install with composer:
composer require arkitechdev/openapi
You can generate the docs by running the following artisan command:
php artisan openapi:generate
The command will create a config file for you if you wish, but you can also publish it with:
php artisan vendor:publish
Configuration
The config file looks like this:
The docs_path contains the path to your doc specification file.
The output_path is where you want the generated API docs to be stored. If the filename has a .json extension, it will be created as a JSON file. If the filename has a .yaml extension, it will be created as a YAML file. It's magic.
Getting started
The library expects a file called docs.php in the root of your project. You can customize this in the config file. To start doc'ing, you can use the OpenApi facade. It works very similar to creating routes in Laravel. Here's an example:
docs.php:
Then simply use the artisan command to generate the Open API docs json or yaml file. Simple!
There a various ways to build your documentation. They are explained below.
Methods
Most of the methods in the classes are somewhat self-explanatory and provides that sweet autocompletion. There is a few things that deserves to be mentioned here though.
Getters and setters
Many of the methods either sets a property value and returns itself, or returns the value of the property in question, if the given parameter is not set or is null.
Examples:
This sets the title property to A title and returns the OpenApi object. This allows for chaining, such as:
Very handy. Meanwhile, if no parameter is set, then the value is returned:
Callbacks
Some method supply callbacks. When setting child objects, such as parameters or properties, the method supplies an optional callback for further definition of the object. Depending on the type you are adding, the first and only parameter of the callback is the added object.
Consider the following example:
Since we add a parameter, the parameter of the callback is a Parameter object. What a great example. Here we add a query param called 'page' of the type integer and sets it as required.
You can structure your whole API docs like this, although I wouldn't recommend it. Consider this rather verbose example.
It can get unmanageable real quick, which is why this library supports splitting everything into classes. I'll go over this in the next chapter.
Method defaults
If you just want to create parameters and properties without all the fuzz, then I've got your back. Notice those null parameters in the example above? That's where the type goes.
Examples:
Actually, string is the default for both parameters and properties, so it can be boiled down even further for that type:
You get the idea.
Other types have other defaults. Feel free to code dive.
Class based API docs
Now, the big example above is only a single endpoint. Imagine having 100 endpoints. That would make it harder to maintain. Ain't nobody got time for that!
As such, if the first parameter of the add...() methods are a class, then you can hide everything inside there. The syntax looks likes this:
You can create and use any class you want as long as it extends the relevant class from the list above. Inside that class you can then use the class properties and inherited methods to define it.
The requests works great that way. You can do something like this in your docs file:
docs.php:
And the custom class would then look something like this:
ProjectIndex.php:
Straight out of Laraville. In this example we have not created Parameter, Response or Property classes, but you could totally go even further. You can do that as many levels deep as you want.
We do have created Schema classes though. That way we can use them as references (more on that in a moment).
I know you're curious, so here it is, the Project schema:
Project.php:
Note: You can still use the callbacks, if you need to overwrite something inside your custom classes. Very nice!
Refs
If you plan to use references to schemas in properties ($property->ref(Project::class)), you have to make sure to add them to the schemas array on the OpenApi object too:
docs.php:
Validator
There's a cool online editor with builtin validator that you can use.
When you have generated your JSON/YAML file, you can paste its contents into the editor and check that it looks fine and dandy.
Roadmap
Things that I would like to do with this package (in no particular order):
- Add more OpenApi features
- Make traits for integration with Laravel models, controllers etc. (to keep the docs closer to the code)
