Documentation

Page last updated on October 18, 2017

One of the most common first question a developer or system integrator asks after getting access to the source code of the project or the API is: where do I find the documentation?  In this section, we have collected all the useful pointers, references, and tips on how to find all the documentation that you need.

CakePHP

First and most important, comes the CakePHP documentation.  Qobrix platform and all Qobrix applications are built on top of the CakePHP framework, so knowing and understanding how the framework works, which features it has and how to use them is critical to figuring out the rest of Qobrix.  CakePHP framework is well known for its excellent documentation.  Mainly, it comes in two parts:

  1. CakePHP Cookbook.  This is an online, frequently updated resource, which documents all of the CakePHP framework.  You can either read it from beginning to end, or navigate your way around the sections of particular interest to you.  We also try to reference this resource as much as we can in the rest of the Qobrix documentation, as well as its source code.
  2. CakePHP API Reference.  This resource provides the documentation for each and every class, method, constant, and variable in the CakePHP source code.  This is indispensable for developers building on top of the CakePHP framework.

Plugins, Components and Dependencies

Qobrix includes a variety of CakePHP plugins, third-party components and dependencies.  The easiest way to find what they are and get to the documentation is by using the Composer.  The two commands particularly useful for this are:

  1. ./bin/composer show , which shows a list of all installed dependencies, including the CakePHP plugins, with their name, version, and description.
  2. ./bin/composer info vendor/package , which shows detailed information about a particular package.  Just replace vendor/package with the package that you are interested in.

In the detailed information of the package, you’ll often find a variety of URLs to documentation, support process, etc.  If documentation URL is not part of the output, just follow the repository (source code) URL, that will take you to the project home.  More often than not, you’ll find either a README file there, or a docs/ folder.  Sometimes, you’ll have both.

Source Code API

Our own source code is well documented as well.  You can navigate this documentation in your Integrated Development Environment (IDE), or you can generate the static HTML files to read with your browser.  In order to generate the new documentation set, or update an existing, previously generated one, you can run one of the following commands:

  • ./vendor/build/phake sami:update, which will regenerate only project-specific documentation.
  • ./vendor/bin/phake sami:update-all,  which will regenerate project-specific documentation, as well as documentation for all Qobrix-related components (this will take a while).
  • ./vendor/bin/phake build:all, which will run all build-related tasks, including the documentation generation, test code coverage, and more.

After successfully executing either one of the above three commands, you can find a collection of the HTML files in the project’s build/doc/source/ folder.  Simply open them up in your browser and navigate around.

Swagger API Documentation

We also have full, up-to-date documentation for all REST API end-points and their parameters and return values, by the means of the Swagger API documentation tool.  Here’s how to get access to that.

  1. Enable Swagger API documentation.
  2. Authenticate.
  3. Access API documentation.

Now with some more details.

Enable Swagger API documentation

By default, we disable Swagger API documentation to limit the exposure of the system internals to the rest of the world.  In order to enable it, you need to adjust your .env file. On the older Qobrix installations, you had to enable the debug mode, by setting DEBUG=1 in your environment configuration.  For the newer systems, we’ve realized that sometimes you want to enable Swagger without enabling the debug mode.  So you have a new environment variable: SWAGGER_CRAWL=1.  For these newer setups, enabling the debug is optional.  It’s up to you.  If you want to have both, enable both, otherwise – just enable the one setting that you need.

Authenticate

Swagger API documentation is generated on demand, based on your access level.  In order for Swagger to know which modules and methods to document for you, it needs to authenticate you as a system user.  You have a few options here:

  1. Disable API authentication completely.  You can do so by setting API_AUTHENTICATION=0 in your .env file.  NOTE: This will completely disable all API authentication for the whole application and anybody sending API requests will be considered an administrator (super-user).  Obviously, this is not something you should do on any publicly available installations, much more so on production environment.
  2. Login into the Qobrix application.  If you login into your Qobrix application with your username and password, your browser will get a user session cookie, which will be respected while browsing Swagger API documentation.
  3. Generate an API token.  You can send an API request to authenticate with username and password and receive the token for your API requests.  You can copy-paste that token into the Swagger web interface, and your documentation and API access will be determined by this token.

Here are some details on how to request the token.   Send an HTTP POST request to /api/users/token.json with the following:

  1. Headers:
    1. Content-Type: application/json
    2. Accept: application/json
  2. Parameters:
    1. username
    2. password

If you are on the command line, here’s an example with cURL (obviously, adjust your details):

$ curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}' http://YOUR_URL/api/users/token.json

Access API Documentation

Once you enable the Swagger and authenticate, you can access the API documentation.  For that just navigate to http://YOUR_URL/swagger/ .  You should see something like this:

Qobrix - API - Swagger - v2.9.0