Overview

​

Core Principle: Single Source of Truth (SSOT)

1. Automated Validation: Requests are validated against the documentation before reaching your controller.
2. Type Safety: Input data is automatically cast to the correct PHP types.
3. IDE Support: DocBlocks are generated to provide autocompletion for request parameters.
4. OpenAPI Specification: A full OpenAPI 3.0 (Swagger) JSON is generated automatically.
5. Reusable Components: Standard response objects can be reused across multiple endpoints.

​

The Documentation Flow

1. Define: You implement getRequestDocumentation() and getResponseDocumentation() in your controllers using the Property System.
2. Generate DocBlocks: Use the DocBlockGenerator to create “Shape” classes and update your request classes with @property tags.
3. Run & Validate: The RequestValidationMiddleware uses your definitions to validate incoming data.
4. Export: The OpenAPIGenerator crawls your routes and documentation to produce a Swagger file.

​

Key Subsystems

• Request Documentation: Defining endpoint input contracts.
• Response Documentation: Defining endpoint output contracts.
• Property Collections: Property Collections in Apivalk are used to group multiple properties together.
• Property System: The building blocks for defining data types and validation rules.
• DocBlock Generator: Enhances the developer experience with IDE support.
• OpenAPI Generator: Converts your code-based documentation into a standard format.
• Response Objects: Pre-defined reusable objects for common API responses.