Download the PHP package srio/api-doc-bundle without Composer

On this page you can find all versions of the php package srio/api-doc-bundle. 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 api-doc-bundle

NelmioApiDocBundle

Build Status

The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs.

Important: This bundle is developed in sync with symfony's repository. For Symfony 2.0.x, you need to use the 1.* version of the bundle.

Installation

Add this bundle to your composer.json file:

{
    "require": {
        "nelmio/api-doc-bundle": "dev-master"
    }
}

Register the bundle in app/AppKernel.php:

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Nelmio\ApiDocBundle\NelmioApiDocBundle(),
    );
}

Import the routing definition in routing.yml:

# app/config/routing.yml
NelmioApiDocBundle:
    resource: "@NelmioApiDocBundle/Resources/config/routing.yml"
    prefix:   /api/doc

Enable the bundle's configuration in app/config/config.yml:

# app/config/config.yml
nelmio_api_doc: ~

Usage

The main problem with documentation is to keep it up to date. That's why the NelmioApiDocBundle uses introspection a lot. Thanks to an annotation, it's really easy to document an API method.

The ApiDoc() annotation

The bundle provides an ApiDoc() annotation for your controllers:

The following properties are available:

Each filter has to define a name parameter, but other parameters are free. Filters are often optional parameters, and you can document them as you want, but keep in mind to be consistent for the whole documentation.

If you set input, then the bundle automatically extracts parameters based on the given type, and determines for each parameter its data type, and if it's required or not.

For classes parsed with JMS metadata, description will be taken from the properties doc comment, if available.

For Form Types, you can add an extra option named description on each field:

The bundle will also get information from the routing definition (requirements, pattern, etc), so to get the best out of it you should define strict _method requirements etc.

Other bundle annotations

Also bundle will get information from the other annotations:

PHPDoc

Route functions marked as @deprecated will be set method as deprecation in documentation.

JMS Serializer features

The bundle has support for some of the JMS Serializer features and use these extra information in the generated documentation.

Group Exclusion Strategy

If your classes use JMS Group Exclusion Strategy, you can specify which groups to use when generating the documentation by using this syntax :

In this case the groups 'update' and 'public' are used.

This feature also works for the output property.

Versioning Objects

If your output classes use versioning capabilities of JMS Serializer, the versioning information will be automatically used when generating the documentation.

Form Types features

If you use FormFactoryInterface::createdNamed('', 'your_form_type', then by default the documentation will use the form type name as the prefix (your_form_type[param] ... instead of just param).

You can specify which prefix to use with the name key:

Documentation on-the-fly

By calling an URL with the parameter ?_doc=1, you will get the corresponding documentation if available.

Web Interface

You can browse the whole documentation at: http://example.org/api/doc.

Command

A command is provided in order to dump the documentation in json, markdown, or html.

php app/console api:doc:dump [--format="..."]

The --format option allows to choose the format (default is: markdown).

For example to generate a static version of your documentation you can use:

php app/console api:doc:dump --format=html > api.html

By default, the generated HTML will add the sandbox feature if you didn't disable it in the configuration. If you want to generate a static version of your documentation without sandbox, use the --no-sandbox option.

Configuration

You can specify your own API name:

# app/config/config.yml
nelmio_api_doc:
    name: My API

This bundle provides a sandbox mode in order to test API methods. You can configure this sandbox using the following parameters:

# app/config/config.yml
nelmio_api_doc:
    sandbox:
        authentication: # default null, if set, the value of the api key is read from the query string and appended to every sandbox api call
            name: access_token
            delivery: query # query or http_basic are supported
            custom_endpoint: true # default false, if true, your user will be able to specify its own endpoint
        enabled:  true # default: true, you can set this parameter to `false` to disable the sandbox
        endpoint: http://sandbox.example.com/ # default: /app_dev.php, use this parameter to define which URL to call through the sandbox
        accept_type: application/json # default null, if set, the value is automatically populated as the Accept header
        body_format: form # default form, determines whether to send x-www-form-urlencoded data or json-encoded data in sandbox requests
        request_format:
            method: format_param # default format_param, alternately accept_header, decides how to request the response format
            default_format: json # default json, alternately xml, determines which content format to request back by default

The bundle provides a way to register multiple input parsers. The first parser that can handle the specified input is used, so you can configure their priorities via container tags. Here's an example parser service registration:

#app/config/config.yml
services:
    mybundle.api_doc.extractor.custom_parser:
        class: MyBundle\Parser\CustomDocParser
        tags:
            - { name: nelmio_api_doc.extractor.parser, priority: 2 }

You can also define your own motd content (above methods list). All you have to do is add to configuration:

#app/config/config.yml
nelmio_api_doc:
    # ...
    motd:
        template: AcmeApiBundle::Components/motd.html.twig

Using Your Own Annotations

If you have developed your own project-related annotations, and you want to parse them to populate the ApiDoc, you can provide custom handlers as services. You just have to implement the Nelmio\ApiDocBundle\Extractor\HandlerInterface and tag it as nelmio_api_doc.extractor.handler:

# app/config/config.yml
services:
    mybundle.api_doc.extractor.my_annotation_handler:
        class: MyBundle\AnnotationHandler\MyAnnotationHandler
        tags:
            - { name: nelmio_api_doc.extractor.handler }

Look at the built-in Handlers.

Credits

The design is heavily inspired by the swagger-ui project. Some icons from the Glyphicons library are used to render the documentation.


All versions of api-doc-bundle with dependencies

PHP Build Version
Package Version
Requires symfony/framework-bundle Version ~2.1
symfony/twig-bundle Version ~2.1
symfony/console Version ~2.1
dflydev/markdown Version 1.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 srio/api-doc-bundle contains the following files

Loading the files please wait ....