18.open-api.md

Note

Attributes used in this document

• #[Produces] - supported by the open api service ✅
• #[IgnoreOpenApi] - supported by the open api service ✅
• #[Summary] - supported by the open api service ✅
• #[Example] - supported by the open api service ✅
• #[Body] - not supported by the open api service ✖

Open API

The web server comes with an open api scanner by default which can be found in the OpenApiService service.

The service will automatically document your route handlers as you're creating them.

In order to obtain the resulting open api json you can use the getData() method.

<?php
use function CatPaw\Core\anyError;
use function CatPaw\Core\success;
use CatPaw\Web\Attributes\IgnoreOpenApi;
use CatPaw\Web\Attributes\Produces;
use CatPaw\Web\Server;
use CatPaw\Web\Services\OpenApiService;
use CatPaw\Core\Unsafe;
use const CatPaw\Web\TEXT_PLAIN;
use const CatPaw\Web\OK;

#[Produces(OK, TEXT_PLAIN, 'string')]
function test() {
    return "this is a test";
}

// this will omit the "/openapi" route
// itself from the documentation
#[IgnoreOpenApi]
function openapi(OpenApiService $openApiService) {
    return success($openApiService->getData());
}

function main():Unsafe {
  return anyError(function(){
    $server = Server::get();
    $server->router->get('/test', test(...))->try();
    $server->router->get("/openapi", openapi(...))->try();
    $server->start()->try();
  });
}

The above code will generate 1 openapi entry for the \CatPaw\Web\Services\OpenApiService service.

OpenAPI Output JSON

{
  "openapi": "3.0.0",
  "info": {
    "title": "OpenAPI",
    "version": "0.0.1"
  },
  "paths": {
    "/test": {
      "get": {
        "summary": "",
        "operationId": "fab75b617f6e066250e96d3501d4406aa5c25170",
        "parameters": [],
        "requestBody": {
          "description": "This is the body of the request",
          "required": true,
          "content": []
        },
        "responses": []
      }
    }
  }
}

Documenting parameters and body

Parameters are documented automatically when injected, but you can also add some extra information like summaries and examples.

<?php
use function CatPaw\Core\anyError;
use CatPaw\Core\Unsafe;
use CatPaw\Web\Attributes\Body;
use CatPaw\Web\Attributes\Example;
use CatPaw\Web\Attributes\Produces;
use CatPaw\Web\Attributes\Summary;
use CatPaw\Web\Server;
use const CatPaw\Web\TEXT_PLAIN;
use const CatPaw\Web\OK;

#[Produces(OK, TEXT_PLAIN, 'on success', 'string')]
function handler(
    #[Body]
    #[Example('this is an example value')]
    #[Summary('this is a summary of the parameter')]
    string $body,
    string $value,
) {
    return "this is a test";
}

function main(): Unsafe {
  return anyError(function(){
    $server = Server::get();

    $server->router->get('/test/{value}', handler(...))->try();

    $server->start()->try();
  });
}

OpenAPI Output JSON

{
  "openapi": "3.0.0",
  "info": {
    "title": "OpenAPI",
    "version": "0.0.1"
  },
  "paths": {
    "/test/{value}": {
      "get": {
        "summary": "",
        "operationId": "92bc1bd07434281f59c47f4857aa504c0642bd2f",
        "parameters": [
          {
            "name": "value",
            "in": "path",
            "description": "this is a summary of the parameter",
            "required": true,
            "schema": {
              "type": "string"
            },
            "examples": {
              "example": {
                "value": "this is an example value"
              }
            }
          }
        ],
        "requestBody": {
          "description": "This is the body of the request",
          "required": true,
          "content": []
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": ""
                }
              }
            }
          }
        }
      }
    }
  }
}