Api doc generator php

Saved searches

Use saved searches to filter your results more quickly

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.

PHP 7.1 ready Smart and Simple Documentation for your PHP project

License

ApiGen/ApiGen

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Sign In Required

Please sign in to use Codespaces.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

Git stats

Files

Failed to load latest commit information.

README.md

Smart and Readable Documentation for PHP projects

ApiGen is easy to use and modern API doc generator supporting all PHP 8.2 features.

• phpDoc
  • all types supported by PHPStan
  • generic class declarations
  • local type aliases
  • constants in traits
  • fetch enum properties in const expressions
  • disjunctive normal form types
  • readonly classes
  • true, false and null types
  • enums
  • pure intersection types
  • never type
  • final class constants
  • new in initializers
  • readonly properties
  • constructor property promotion
  • union types
  • mixed type
  • static return type
  • typed properties
  • object type
  • nullable types
  • iterable type
  • void type
  • class constant visibility
  • scalar types
  • return types
  • constant scalar expressions
  • variadic functions
  • traits
  • callable type
  • binary integer notation

  Built on Shoulders of Giants

  ApiGen is available as apigen/apigen Docker image which you can directly use.

  docker run --rm --interactive --tty --volume "$PWD:$PWD" --workdir "$PWD" \ apigen/apigen:edge \ src --output docs

  This will install ApiGen phar binary to tools/apigen .

  mkdir -p tools curl -L https://github.com/ApiGen/ApiGen/releases/latest/download/apigen.phar -o tools/apigen chmod +x tools/apigen tools/apigen src --output docs

  This will install ApiGen to tools/apigen directory with executable entry point available in tools/apigen/bin/apigen .

  composer create-project --no-dev apigen/apigen:^7.0@alpha tools/apigen tools/apigen/bin/apigen src --output docs

  Generate API docs by passing source directories and destination option:

  ApiGen can be configured with apigen.neon configuration file.

  parameters: # string[], passed as arguments in CLI, e.g. ['src'] paths: [] # string[], --include in CLI, included files mask, e.g. ['*.php'] include: ['*.php'] # string[], --exclude in CLI, excluded files mask, e.g. ['tests/**'] exclude: [] # bool, should protected members be excluded? excludeProtected: false # bool, should private members be excluded? excludePrivate: true # string[], list of tags used for excluding class-likes and members excludeTagged: ['internal'] # string, --output in CLI outputDir: '%workingDir%/api' # string | null, --theme in CLI themeDir: null # string, --title in CLI title: 'API Documentation' # string, --base-url in CLI baseUrl: '' # int, --workers in CLI, number of processes that will be forked for parallel rendering workerCount: 8 # string, --memory-limit in CLI memoryLimit: '512M'

  About

  PHP 7.1 ready Smart and Simple Documentation for your PHP project

  Источник

  API Docs Generator

  Apiato make writing and generating documentations very easy with the php artisan apiato:apidoc command.

  Alternatively you can generate a swagger doc from the apidoc comments, to do so run php artisan apiato:swagger command.

  Requirements​

  Usage​

  1 — Write a PHP docblock on top of your endpoint like this:​

  For more info about the parameters check out ApiDocJs documentation

     /**  * @apiGroup Authentication  * @apiName UserLogin  * @api /users/login User Login  * @apiDescription Description Here.  * @apiVersion 1.0.0  * @apiPermission none  *  * @apiHeader Accept application/json  *  * @apiParam email  * @apiParam password  *  * @apiSuccessExample Success-Response:  * HTTP/1.1 200 OK  *  * "data":  * "id": "owpzanmh",  * "name": "Super Admin",  * "email": "[email protected]"  * .  * >  *  * @apiErrorExample Error-Response:  *  * "message":"401 Credentials Incorrect.",  * "status_code":401  * >  *  * @apiErrorExample Error-Response:  *  * "message":"Invalid Input.",  * "errors":  * "email":[  * "The email field is required."  * ]  * >,  * "status_code":422  * >  */  $router->post('users/login', [ 'uses' => '[email protected]', ]); 

  Note: All the Endpoints DocBlocks MUST be written inside Routes files, otherwise they won’t be loaded.

  2 — Run the documentation generator command from the root directory:​

  3 — Visit this URL’s as shown in your terminal:​

  

  

  NOTE: Every time you change the DocBlock of a Route file you need to run the apiato:apidoc command, to regenerate.

  Generate Swagger/OpenAPI JSON schema from apiDoc​

  It’s also possible to generate a Swagger/OpenAPI JSON schema from apiDoc with:

   php artisan apiato:swagger 

  Error: ApiDoc not found !!​

  If you get an error ( apidoc not found ),

  1. open the container config file Containers/Documentation/Configs/apidoc.php
  2. edit the executable path to $(npm bin)/apidoc or to however you access the apidoc tool on your machine.

    /*  |--------------------------------------------------------------------------  | Executable  |--------------------------------------------------------------------------  |  | Specify how you run or access the `apidoc` tool on your machine.  |  */  'executable' => 'apidoc', 

  Shared response for faster updating and less outdated responses:​

  To prevent duplicating the responses between routes, let’s create a shared response for each object.

  Example: _user.v1.public.php will contain all responses (single, multiple. ) of the User:

     /**  * @apiDefine UserSuccessSingleResponse  * @apiSuccessExample Success-Response: HTTP/1.1 200 OK   "data":  "object":"User",  "id":eqwja3vw94kzmxr0,  >,  "meta":  "include":[],  "custom":[]  > >  */ 

  Usage of the shared User response from any endpoint:

  * @apiUse UserSuccessSingleResponse 

  To avoid having to generate and update the Single and Multiple responses of the same object (recommended only for private API’s) you can use the general shared Multiple Response * @apiUse GeneralSuccessMultipleResponse which you can find and modify it from app/Containers/Documentation/UI/API/Routes/*

  Edit the default generated values in the templates:​

  Apiato generates by defaults 2 API documentations, each one has its own apidoc.json file. Both can be modified from the Documentation Containers in Containers/Documentation/ApiDocJs/

    "name": "Apiato", "description": "Apiato (Private API) Documentation", "title": "Welcome to Apiato", "version": "1.0.0", "url" : "http://api.apiato.test", "template":   "withCompare": true, "withGenerator": true >, "header":   "title": "API Overview", "filename": "app/Containers/Documentation/ApiDocJs/private/header.md" >, "footer":   "title": "Footer", "filename": "app/Containers/Documentation/ApiDocJs/private/header.md" >, "order": [  ] > 

  Change the Documentations URL’s​

  Edit the config file of the Documentation Container Containers/Documentation/Configs/apidoc.php

     return [  /*  |--------------------------------------------------------------------------  | Executable  |--------------------------------------------------------------------------  |  | Specify how you run or access the `apidoc` tool on your machine.  |  */  'executable' => 'apidoc',  /*  |--------------------------------------------------------------------------  | API Types  |--------------------------------------------------------------------------  |  | The `types` helps generating multiple documentations, by grouping them  | under types names. You can add or remove any type. By default  | `public` and `private` types are set.  |  | url: The url to access that generated API documentation.  |  | routes: The route file to read when generating this documentation.  | Every route file will have the following name format:  | `.v..php`.  |  */  'types' => [  'public' => [ 'url' => 'api/documentation', 'routes' => [ 'public', ], ],  'private' => [ 'url' => 'api/private/documentation', 'routes' => [ 'private', 'public', ], ], ],   /*  |--------------------------------------------------------------------------  | HTML files  |--------------------------------------------------------------------------  |  | Specify where to put the generated HTML files.  |  */  'html_files' => 'public/'   // . ]; 

  Edit the Documentation Header​

  The header is usually the Overview of your API. It contains Info about authenticating users, making requests, responses, potential errors, rate limiting, pagination, query parameters and anything you want.

  All this information is written in app/Containers/Documentation/ApiDocJs/shared/header.template.md file, and the same file is used as header for both private and public documentations.

  To edit the content just open the markdown file in any markdown editor and edit it.

  You will notice some variables like > and > . Those are replaced when running apidoc:generate with real values from your application configuration files.

  Feel free to extend them to include more info about your API from the app/Containers/Documentation/Actions/ProcessMarkdownTemplatesAction.php class.

  Источник