Back to Learning Hub

API Documentation

15 minutes INTERMEDIATE

Discover GEMVC's automatic API documentation system. Learn how sanitization creates documentation, use PHPDoc directives, and export to Postman with one click.

What You'll Learn

Automatic Documentation

How GEMVC auto-generates docs from your code

PHPDoc Directives

Use @http, @description, @example directives

Postman Export

One-click export to Postman collection

Video Coming Soon...

What is GEMVC API Documentation?

GEMVC has a built-in automatic API documentation generator that creates beautiful, interactive HTML documentation from your code! The most interesting part: when you sanitize input in the API layer, GEMVC automatically generates documentation!

  • Automatic Generation - Documentation is created automatically from your validation schemas
  • Always Up-to-Date - Uses reflection to scan your code, so docs never get outdated
  • Beautiful UI/UX - Full graphical interface that frontend developers will love
  • Postman Export - One-click export to Postman collection for easy testing
  • Parameter Extraction - Automatically extracts parameters from definePostSchema() and defineGetSchema()

Key Point: In GEMVC, sanitization IS documentation! When you use definePostSchema() or defineGetSchema() to validate inputs, GEMVC automatically extracts those parameters and creates beautiful documentation tables for your frontend developers.

1

How Automatic Documentation Works

The Magic: Sanitization = Documentation

GEMVC's ApiDocGenerator uses reflection to scan your API service classes and automatically extracts:

1. Parameters from Validation Schemas

When you use definePostSchema() or defineGetSchema(), GEMVC automatically extracts all parameters and creates parameter tables in the documentation.

Automatic Parameter Extraction 
<?php
public function create(): JsonResponse
{
    // This schema automatically creates documentation!
    if(!$this->request->definePostSchema([
        'name' => 'string',        // Required parameter
        'email' => 'email',         // Required parameter
        '?phone' => 'string'       // Optional parameter (? prefix)
    ])) {
        return $this->request->returnResponse();
    }
    // ...
}

Result: Documentation automatically shows a "Body Parameters" table with name, email, and phone fields, including which are required/optional!

2. PHPDoc Directives

PHPDoc comments with special directives provide additional information:

  • ✓ @http GET/POST/PUT/DELETE - HTTP method
  • ✓ @description - Human-readable description
  • ✓ @example - Example URL
  • ✓ @hidden - Hide method from docs

3. Mock Responses

The mockResponse() static method provides example responses that are displayed in the documentation.

2

Accessing Your API Documentation

View Documentation

GEMVC automatically creates a documentation endpoint. Simply visit:

Documentation URL:

http://localhost/api/index/document

Replace localhost with your server URL. For OpenSwoole, use localhost:9501.

What You'll See:

  • ✓ Beautiful, modern UI with clean design
  • ✓ All your API endpoints organized by service
  • ✓ Parameter tables (automatically extracted from schemas)
  • ✓ Example URLs (from @example directives)
  • ✓ Mock responses (from mockResponse() method)
  • ✓ One-click "Export to Postman" button
  • ✓ Interactive elements (click to copy URLs)
3

Using PHPDoc Directives

Documenting Your API Methods

Add PHPDoc comments with special directives to enhance your documentation:

app/api/Product.php - Complete Example with Directives 
<?php
namespace App\Api;

use App\Controller\ProductController;
use Gemvc\Core\ApiService;
use Gemvc\Http\Request;
use Gemvc\Http\JsonResponse;

class Product extends ApiService
{
    /**
     * Create new Product
     * 
     * @return JsonResponse
     * @http POST
     * @description Create new Product in database. Only admin and salesManager can create products.
     * @example /api/Product/create
     */
    public function create(): JsonResponse
    {
        if (!$this->request->auth(['admin', 'salesManager'])) {
            return $this->request->returnResponse();
        }
        
        if(!$this->request->definePostSchema([
            'name' => 'string',
            'price' => 'float',
            '?description' => 'string'
        ])) {
            return $this->request->returnResponse();
        }
        
        return (new ProductController($this->request))->create();
    }

    /**
     * Read Product by ID
     * 
     * @return JsonResponse
     * @http GET
     * @description Get Product by id from database
     * @example /api/Product/read/?id=1
     */
    public function read(): JsonResponse
    {
        if (!$this->request->auth()) {
            return $this->request->returnResponse();
        }
        
        if(!$this->request->defineGetSchema(['id' => 'int'])) {
            return $this->request->returnResponse();
        }
        
        $id = $this->request->intValueGet('id');
        if(!$id) {
            return $this->request->returnResponse();
        }
        
        $this->request->post['id'] = $id;
        return (new ProductController($this->request))->read();
    }
}

Available Directives:

  • @http GET/POST/PUT/DELETE
    Specifies the HTTP method for the endpoint
  • @description Your description here
    Human-readable description shown in documentation
  • @example /api/Product/create
    Example URL showing how to call the endpoint
  • @hidden
    Hides the method from API documentation (useful for helper methods)
4

Adding Mock Responses

Example Responses in Documentation

Add a mockResponse() static method to provide example responses that will be displayed in the documentation:

app/api/Product.php - Mock Response Method 
<?php
class Product extends ApiService
{
    // ... your API methods ...

    /**
     * Generates mock responses for API documentation
     * 
     * @param string $method The API method name
     * @return array<mixed> Example response data for the specified method
     * @hidden
     */
    public static function mockResponse(string $method): array
    {
        return match($method) {
            'create' => [
                'response_code' => 201,
                'message' => 'created',
                'count' => 1,
                'service_message' => 'Product created successfully',
                'data' => [
                    'id' => 1,
                    'name' => 'Sample Product',
                    'price' => 99.99,
                    'description' => 'Product description'
                ]
            ],
            'read' => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => 1,
                'service_message' => 'Product retrieved successfully',
                'data' => [
                    'id' => 1,
                    'name' => 'Sample Product',
                    'price' => 99.99,
                    'description' => 'Product description'
                ]
            ],
            'update' => [
                'response_code' => 209,
                'message' => 'updated',
                'count' => 1,
                'service_message' => 'Product updated successfully',
                'data' => [
                    'id' => 1,
                    'name' => 'Updated Product',
                    'price' => 149.99
                ]
            ],
            'delete' => [
                'response_code' => 210,
                'message' => 'deleted',
                'count' => 1,
                'service_message' => 'Product deleted successfully',
                'data' => null
            ],
            default => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => null,
                'service_message' => null,
                'data' => null
            ]
        };
    }
}

Key Points:

  • ✓ Method must be static and named mockResponse()
  • ✓ Use @hidden directive to hide it from documentation
  • ✓ Returns an array matching the method name
  • ✓ Example responses are displayed beautifully in the documentation UI
  • ✓ Helps frontend developers understand response structure
5

Automatic Parameter Extraction

How Schemas Create Documentation

The most powerful feature: GEMVC automatically extracts parameters from your validation schemas! No need to manually document parameters.

POST Parameters

POST Schema Example 
<?php
public function create(): JsonResponse
{
    // This automatically creates documentation!
    if(!$this->request->definePostSchema([
        'name' => 'string',        // Required
        'price' => 'float',        // Required
        '?description' => 'string' // Optional (? prefix)
    ])) {
        return $this->request->returnResponse();
    }
    // ...
}

Result: Documentation automatically shows a "Body Parameters" table with name (string, required), price (float, required), and description (string, optional).

GET Parameters

GET Schema Example 
<?php
public function read(): JsonResponse
{
    // This automatically creates documentation!
    if(!$this->request->defineGetSchema([
        'id' => 'int'
    ])) {
        return $this->request->returnResponse();
    }
    // ...
}

Result: Documentation automatically shows a "GET Parameters" table with id (int, required).

Query Parameters (List Operations)

Query Parameters Example 
<?php
public function list(): JsonResponse
{
    // Findable fields automatically documented
    $this->request->findable([
        'name' => 'string',
        'price' => 'float'
    ]);
    
    // Sortable fields automatically documented
    $this->request->sortable([
        'id',
        'name',
        'price'
    ]);
    
    // ...
}

Result: Documentation automatically shows "Query Parameters" with Filters (name, price) and Sort (id, name, price) sections.

💡 The Magic:

When you sanitize input using definePostSchema() or defineGetSchema(), you're not just validating data - you're automatically creating documentation! GEMVC reads your schemas and generates beautiful parameter tables that your frontend developers will love.

6

Export to Postman

One-Click Postman Export

GEMVC provides a one-click export to Postman! Simply click the "Export to Postman" button in the documentation UI, and you'll get a fully functional Postman collection.

How to Export:

  1. 1. Visit http://localhost/api/index/document
  2. 2. Scroll to the top of the documentation page
  3. 3. Click the "Export to Postman" button
  4. 4. Download the api_collection.json file
  5. 5. Import into Postman: File → Import → Select the JSON file

What Gets Exported:

  • ✓ All API endpoints with correct HTTP methods
  • ✓ Request URLs (from @example directives)
  • ✓ Request body schemas (from definePostSchema())
  • ✓ Query parameters (from defineGetSchema())
  • ✓ Example responses (from mockResponse())
  • ✓ Organized by service (Product, User, etc.)

Benefits for Frontend Developers:

  • ✓ No manual setup - Everything is pre-configured
  • ✓ Ready to test - All endpoints are ready to use
  • ✓ Always up-to-date - Export again when API changes
  • ✓ Team collaboration - Share the collection with your team
7

Complete Example

Fully Documented Product API

Here's a complete example showing all documentation features:

app/api/Product.php - Complete Documentation Example 
<?php
namespace App\Api;

use App\Controller\ProductController;
use Gemvc\Core\ApiService;
use Gemvc\Http\Request;
use Gemvc\Http\JsonResponse;

class Product extends ApiService
{
    /**
     * Create new Product
     * 
     * @return JsonResponse
     * @http POST
     * @description Create new Product in database. Only admin and salesManager can create products.
     * @example /api/Product/create
     */
    public function create(): JsonResponse
    {
        if (!$this->request->auth(['admin', 'salesManager'])) {
            return $this->request->returnResponse();
        }
        
        // Parameters automatically extracted for documentation!
        if(!$this->request->definePostSchema([
            'name' => 'string',
            'price' => 'float',
            '?description' => 'string'
        ])) {
            return $this->request->returnResponse();
        }
        
        return (new ProductController($this->request))->create();
    }

    /**
     * Read Product by ID
     * 
     * @return JsonResponse
     * @http GET
     * @description Get Product by id from database
     * @example /api/Product/read/?id=1
     */
    public function read(): JsonResponse
    {
        if (!$this->request->auth()) {
            return $this->request->returnResponse();
        }
        
        // GET parameter automatically extracted for documentation!
        if(!$this->request->defineGetSchema(['id' => 'int'])) {
            return $this->request->returnResponse();
        }
        
        $id = $this->request->intValueGet('id');
        if(!$id) {
            return $this->request->returnResponse();
        }
        
        $this->request->post['id'] = $id;
        return (new ProductController($this->request))->read();
    }

    /**
     * List all Products
     * 
     * @return JsonResponse
     * @http GET
     * @description Get list of all Products with filtering and sorting
     * @example /api/Product/list/?sort_by=name&find_like=name=test
     */
    public function list(): JsonResponse
    {
        // Query parameters automatically extracted for documentation!
        $this->request->findable([
            'name' => 'string',
            'price' => 'float'
        ]);
        
        $this->request->sortable([
            'id',
            'name',
            'price'
        ]);
        
        return (new ProductController($this->request))->list();
    }

    /**
     * Generates mock responses for API documentation
     * 
     * @param string $method The API method name
     * @return array<mixed> Example response data for the specified method
     * @hidden
     */
    public static function mockResponse(string $method): array
    {
        return match($method) {
            'create' => [
                'response_code' => 201,
                'message' => 'created',
                'count' => 1,
                'service_message' => 'Product created successfully',
                'data' => [
                    'id' => 1,
                    'name' => 'Sample Product',
                    'price' => 99.99,
                    'description' => 'Product description'
                ]
            ],
            'read' => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => 1,
                'service_message' => 'Product retrieved successfully',
                'data' => [
                    'id' => 1,
                    'name' => 'Sample Product',
                    'price' => 99.99,
                    'description' => 'Product description'
                ]
            ],
            'list' => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => 2,
                'service_message' => 'Products retrieved successfully',
                'data' => [
                    [
                        'id' => 1,
                        'name' => 'Product 1',
                        'price' => 99.99
                    ],
                    [
                        'id' => 2,
                        'name' => 'Product 2',
                        'price' => 149.99
                    ]
                ]
            ],
            default => [
                'response_code' => 200,
                'message' => 'OK',
                'count' => null,
                'service_message' => null,
                'data' => null
            ]
        };
    }
}

What This Creates in Documentation:

  • ✓ create() - Shows POST method, description, example URL, body parameters table (name, price, description), and mock response
  • ✓ read() - Shows GET method, description, example URL, GET parameters table (id), and mock response
  • ✓ list() - Shows GET method, description, example URL, query parameters (filters and sort), and mock response
  • ✓ mockResponse() - Hidden from docs but provides example responses for all methods

Documentation Features

GEMVC's documentation system provides a fantastic experience for frontend developers:

✨ Auto-Generated

Documentation is automatically created from your code using reflection. No manual writing needed!

🔄 Always Up-to-Date

Since it scans your code, documentation is always synchronized with your API. No outdated docs!

📦 Postman Export

One-click export to Postman collection. Fully functional, ready to use immediately!

🎨 Beautiful UI/UX

Modern, clean design with interactive elements. Frontend developers will love it!

📋 Parameter Tables

Automatic parameter extraction from schemas creates beautiful, organized tables.

🔗 Interactive

Click to copy URLs, expand/collapse sections, and navigate easily through your API.

Important Notes

  • Sanitization = Documentation: When you use definePostSchema() or defineGetSchema(), you're automatically creating documentation. No extra work needed!
  • Optional Parameters: Use ? prefix (e.g., '?description' => 'string') to mark parameters as optional in documentation.
  • Always Include Directives: Add @http, @description, and @example to all public API methods for best documentation.
  • Mock Responses: Always include a mockResponse() method to provide example responses for frontend developers.
  • Hide Helper Methods: Use @hidden directive on methods that shouldn't appear in documentation (like mockResponse()).

📚 Documentation Complete!

Excellent! You've learned how GEMVC automatically generates beautiful API documentation. Your frontend developers will love the interactive UI and one-click Postman export!

Back to Learning Hub View API Docs Reference