README

OpenApi package for Bone Framework

installation

Use Composer

composer require delboy1978uk/open-api

setup

Simply add to the config/packages.php

<?php

// use statements here
use Bone\OpenApi\OpenApi\OpenApiPackage;

return [
    'packages' => [
        // packages here...,
        OpenApiPackage::class,
    ],
    // ...
];

Create a config array entry/file. You can add a (client_credentials) client so the docs page can authorize and test your endpoints.

<?php

return [
    'docs' => 'data/docs/api.json',
    'swaggerClient' => [
        'clientId' => '',
        'clientSecret' => '',
    ],
];

Run booty to deploy the front end assets.

vendor/bin/bone assets:deploy

If you do not have an npm project yet, you can simply run

vendor/bin/bone docs:setup

which will create a package.json and typespec config file, as well as the spec folder and files for your API definitions, including definitions from vendor packages.

If you already have a pacakage.json, then your files will be left untouched. You should add the following to your package.json

{
  "devDependencies": {
    "@typespec/compiler": "^1.5.0",
    "@typespec/http": "^1.5.0",
    "@typespec/openapi3": "^1.5.0",
    "@typespec/rest": "^0.75.0",
    "@typespec/versioning": "^0.75.0"
  },
  "scripts": {
    "docs": "tsp compile ./spec"
  }
}

Now you can run vendor/bin/bone docs:setup.

vendor package API definitions

Vendor packages can also provide API definitions. These are loaded in to the vendor.tsp files in the spec folder. These files are autogenerated and ashould not be edited.

To update the vendor definitions, run

vendor/bin/bone docs:vendor-update

compiling open api docs

To create the OpenApi definition file, we compile the docs using the following command (be it npm, pnpm, or yarn)

pnpm run docs

Now you can head to /api/docs to view your API documentation. 😃 Click on the Authorize button, your client ID and secret should already be populated, so click Authorize again, and you are ready to start calling your endpoints!