Download the PHP package alvinone/idoc without Composer

On this page you can find all versions of the php package alvinone/idoc. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

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 PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • 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.
Please rate this library. Is it a good library?

Informations about the package idoc



Latest Stable Version Total Downloads License



Laravel IDoc - The API Documentation Generator

Automatically generate an interactive API documentation from your existing Laravel routes. Take a look at the example documentation. Inspired by Laravel Api Documentation Generator



Introduction.

Laravel IDoc generator (interactive documentation generator) is a seamless and complete plugin for generating API documentation from your Laravel's codebase. It is inspired by the laravel-apidoc-generator, ReDoc and the Open API initiative from Swagger. IDoc has been built with extendability so that it can easily adapt with your use case.

Demo

Features

Installation

Note: PHP 7 and Laravel 5.5 or higher are the minimum dependencies.

Laravel

Publish the config file by running:

This will create an idoc.php file in your config folder.

Lumen

Usage

Configuration

Before you can generate your documentation, you'll need to configure a few things in your config/idoc.php.

For instance, suppose your configuration looks like this:

This means documentation will be generated for routes in all domains ('*' is a wildcard meaning 'any character') which match any of the patterns 'api/*' or 'v2-api/*', excluding the 'users.create' route and any routes whose names begin with admin., and including the 'users.index' route and any routes whose names begin with healthcheck.. (The versions key is ignored unless you are using Dingo router). Also, in the generated documentation, these routes will have the header 'Authorization: Bearer: {token}' added to the example requests.

You can also separate routes into groups to apply different rules to them:

With the configuration above, routes on the v1.* domain will have the Token and Version headers applied, while routes on the v2.* domain will have the Authorization and Api-Version headers applied.

Note: the include and exclude items are arrays of route names. THe * wildcard is supported. Note: If you're using DIngo router, the versions parameter is required in each route group. This parameter does not support wildcards. Each version must be listed explicitly,

To generate your API documentation, use the idoc:generate artisan command.

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.

They will be included in the generated documentation text and example requests.

Result: Result

Note: a random value will be used as the value of each parameter in the example requests. If you'd like to specify an example value, you can do so by adding Example: your-example to the end of your description. For instance:

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:

  1. 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's transform() method.
  2. Get an instance of the model from the Eloquent model factory
  3. If the parameter is an Eloquent model, load the first from the database.
  4. 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:

For the first route above, this package will generate a set of two users then pass it through the transformer. For the last two, it will generate a single user and then pass it through the transformer.

Note: for transformer support, you need to install the league/fractal package

@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:

Generating responses automatically

If you don't specify an example response using any of the above means, this package will attempt to get a

response by making a request to the route (a "response call"). A few things to note about response calls:

Open-API 3.0 spec file

The generator automatically creates an Open-API 3.0 spec file, which you can import to use within any external api application.

The default base URL added to the spec file will be that found in your Laravel config/app.php file. This will likely be http://localhost. If you wish to change this setting you can directly update the url or link this config value to your environment file to make it more flexible (as shown below):

If you are referring to the environment setting as shown above, then you should ensure that you have updated your .env file to set the APP_URL value as appropriate. Otherwise the default value (http://yourappdefault.app) will be used in your spec file. Example environment value:

Further modification

The info file in the view folder can be further modified to add introductions and further documentation.

Credits

This software uses the following open source packages:

You may also like...

License

MIT


All versions of idoc with dependencies

PHP Build Version
Package Version
Requires php Version >=7.0.0
fakerphp/faker Version ^1.12
illuminate/routing Version 5.5.* || 5.6.* || 5.7.* || 5.8.* || ^6.0 || ^7.0 || ^8.0
illuminate/support Version 5.5.* || 5.6.* || 5.7.* || 5.8.* || ^6.0 || ^7.0 || ^8.0
illuminate/console Version 5.5.* || 5.6.* || 5.7.* || 5.8.* || ^6.0 || ^7.0 || ^8.0
mpociot/reflection-docblock Version ^1.0.1
ramsey/uuid Version ^3.8 || ^4.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package alvinone/idoc contains the following files

Loading the files please wait ....