Download the PHP package laililmahfud/apdoc without Composer
On this page you can find all versions of the php package laililmahfud/apdoc. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download laililmahfud/apdoc
More information about laililmahfud/apdoc
Files in laililmahfud/apdoc
Package apdoc
Short Description Generate beautiful API documentation from your Laravel application
License MIT
Informations about the package apdoc
ApDoc for Laravel - The API Documentation Generator Fork From Laravel IDoc
Automatically generate an interactive API documentation from your existing Laravel routes.
Installation
Note: PHP 8 and Laravel 9.19 or higher are the minimum dependencies.
Laravel
Publish the config file by running:
This will create an apdoc.php
file in your config
folder.
Configuration
Before you can generate your documentation, you'll need to configure a few things in your config/apdoc.php
.
-
path
This will be used to register the necessary routes for the package. -
title
Here, you can specify the title to place on the documentation page. -
description
This will place a description on top of the documentation. -
version
Documentation version number. -
output
This package can automatically generate an Open-API 3.0 specification file for your routes, along with the documentation. This is the file path where the generated documentation will be written to. Default: storage/api-docs -
servers
The servers array can be used to add multiple endpoints on the documentation so that the user can switch between endpoints. For example, This could be a test server and the live server. security
This is where you specify authentication and authorization schemes, by default the HTTP authentication scheme using Bearer is setting but you can modify it, add others or even define it as null according to the requirements of your project. For more information, please visit Swagger Authentication.
It will generate documentation using your specified configuration.
Documenting your API
This package uses these resources to generate the API documentation:
Grouping endpoints
This package uses the HTTP controller doc blocks to create a table of contents and show descriptions for your API methods.
Using @group
in a controller doc block creates a Group within the API documentation. All routes handled by that controller will be grouped under this group in the sidebar. The short description after the @group
should be unique to allow anchor tags to navigate to this section. A longer description can be included below. Custom formatting and <aside>
tags are also supported. (see the Documentarian docs)
Note: using
@group
is optional. Ungrouped routes will be placed in a "general" group.
Above each method within the controller you wish to include in your API documentation you should have a doc block. This should include a unique short description as the first entry. An optional second entry can be added with further information. Both descriptions will appear in the API documentation in a different format as shown below.
You can also specify an @group
on a single method to override the group defined at the controller level.
Specifying request parameters
To specify a list of valid parameters your API route accepts, use the @bodyParam
, @queryParam
and @pathParam
annotations.
- The
@bodyParam
annotation takes the name of the parameter, its type, an optional "required" label, and then its description. - The
@queryParam
annotation takes the name of the parameter, an optional "required" label, and then its description - The
@pathParam
annotation takes the name of the parameter, an optional "required" label, and then its description - The
@defaultParam
annotation takes the default param - The
@requestBody
annotation to make request body type, default isapplication/json
- The
@header
annotation to make header param => the name of the parameter, its type, an optional "required" label, and then its description.
Note: You can also add the @bodyParam
annotations to a \Illuminate\Foundation\Http\FormRequest
subclass:
Indicating auth status
You can use the @authenticated
annotation on a method to indicate if the endpoint is authenticated. A field for authentication token will be made available and marked as required on the interractive documentation.
Providing an example response
You can provide an example response for a route. This will be displayed in the examples section. There are several ways of doing this.
@response
You can provide an example response for a route by using the @response
annotation with valid JSON:
Moreover, you can define multiple @response
tags as well as the HTTP status code related to a particular response (if no status code set, 200
will be returned):
@transformer, @transformerCollection, and @transformerModel
You can define the transformer that is used for the result of the route using the @transformer
tag (or @transformerCollection
if the route returns a list). The package will attempt to generate an instance of the model to be transformed using the following steps, stopping at the first successful one:
- Check if there is a
@transformerModel
tag to define the model being transformed. If there is none, use the class of the first parameter to the transformer'stransform()
method. - Get an instance of the model from the Eloquent model factory
- If the parameter is an Eloquent model, load the first from the database.
- Create an instance using
new
.
Finally, it will pass in the model to the transformer and display the result of that as the example response.
For example:
@responseFile
For large response bodies, you may want to use a dump of an actual response. You can put this response in a file (as a JSON string) within your Laravel storage directory and link to it. For instance, we can put this response in a file named users.get.json
in storage/responses
:
Then in your controller, link to it by:
The package will parse this response and display in the examples for this route.
Similarly to @response
tag, you can provide multiple @responseFile
tags along with the HTTP status code of the response:
You may also like...
- Laravel Api Documentation Generator - A laravel api documentation generator.
License
MIT