feat: generate OpenAPI JSON from APIB

.github/workflows/test.yml

@@ -85,6 +85,89 @@ jobs:
           name: coverage-${{ matrix.php-versions }}
           path: coverage.xml
 
+  openapi:
+    name: File generation
+    needs: test
+    runs-on: ubuntu-latest
+    env:
+      PHPDRAFT_THIRD_PARTY: 1
+      extensions: curl,json,mbstring,uopz
+      key: cache-v1 # can be any string, change to clear the extension cache.
+    strategy:
+      matrix:
+        php-versions: [ '8.3' ]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
+
+      - name: Setup cache environment
+        id: extcache
+        uses: shivammathur/cache-extensions@v1
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: ${{ env.extensions }}
+          key: ${{ env.key }}
+
+      - name: Cache extensions
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.extcache.outputs.dir }}
+          key: ${{ steps.extcache.outputs.key }}
+          restore-keys: ${{ steps.extcache.outputs.key }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-versions }}
+          extensions: ${{ env.extensions }}
+          coverage: pcov
+          tools: pecl,phpunit
+
+      - name: Get Composer Cache Directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --ignore-platform-reqs
+
+      - name: Generate OpenAPI definition and HTML
+        run: php ./phpdraft --online --file tests/statics/full_test.apib --openapi openapi.json > out.html 2> error.txt || true
+
+      - name: Install check-jsonschema
+        run: pipx install check-jsonschema
+
+      - name: Validate OpenAPI spec
+        run: |
+          if [ -s "error.txt" ]; then
+            echo "The file 'error.txt' is not empty."
+            cat error.txt
+            exit 1
+          fi
+
+          if [ ! -s "index.html" ]; then
+            echo "The file 'index.html' is empty."
+            exit 1
+          fi
+
+          if [ ! -s "openapi.json" ]; then
+            echo "The file 'openapi.json' is empty."
+            exit 1
+          fi
+
+          check-jsonschema --schemafile https://spec.openapis.org/oas/3.1/schema/latest openapi.json
+
   analytics:
     name: Analytics
     needs: test

.gitignore

@@ -11,7 +11,6 @@
 /build/out
 /build/*.phar
 /tests/statics/index.*
-src/Michelf/*
 src/.gitignore
 vendor/**
 
@@ -21,6 +20,8 @@ atlassian-ide-plugin.xml
 *.pem
 
 /index.html
+/openapi.json
 
 /coverage.xml
 /event.json
+!/src/PHPDraft/Out/

phpdraft

@@ -28,6 +28,7 @@ try
         ->opt('help:h', 'This help text', false)
         ->opt('version:v', 'Print the version for PHPDraft.', false)
         ->opt('file:f', 'Specifies the file to parse.', false)
+        ->opt('openapi:a', 'Output location for an OpenAPI file.', false)
         ->opt('yes:y', 'Always accept using the online mode.', false, 'bool')
         ->opt('online:o', 'Always use the online mode.', false, 'bool')
         ->opt('template:t', 'Specifies the template to use. (defaults to \'default\').', false)
@@ -90,6 +91,11 @@ try
         $data = json_decode($json_string);
     }
 
+    if (isset($args['openapi'])) {
+        $openapi = ParserFactory::getOpenAPI()->init($data);
+        $openapi->write($args['openapi']);
+    }
+
     $html          = ParserFactory::getJson()->init($data);
     $name          = 'PHPD_SORT_' . strtoupper($args->getOpt('sort', ''));
     $html->sorting = Sorting::${$name} ?? Sorting::PHPD_SORT_NONE->value;

src/PHPDraft/Model/HTTPRequest.php

@@ -12,6 +12,7 @@
 
 namespace PHPDraft\Model;
 
+use PHPDraft\Model\Elements\ObjectStructureElement;
 use PHPDraft\Model\Elements\RequestBodyElement;
 use PHPDraft\Model\Elements\StructureElement;
 
@@ -43,7 +44,7 @@ class HTTPRequest implements Comparable
      *
      * @var string
      */
-    public string $description;
+    public string $description = '';
 
     /**
      * Parent class.
@@ -68,9 +69,10 @@ class HTTPRequest implements Comparable
     /**
      * Structure of the request.
      *
-     * @var RequestBodyElement[]|RequestBodyElement
+     * @var RequestBodyElement[]|RequestBodyElement|ObjectStructureElement
      */
-    public mixed $struct = [];
+    public RequestBodyElement|ObjectStructureElement|array|null $struct = [];
+
     /**
      * Identifier for the request.
      *

src/PHPDraft/Model/Transition.php

@@ -23,9 +23,9 @@ class Transition extends HierarchyElement
     /**
      * HTTP method used.
      *
-     * @var string
+     * @var string|null
      */
-    public string $method;
+    public ?string $method = NULL;
 
     /**
      * URI.

src/PHPDraft/Out/BaseTemplateRenderer.php

@@ -24,36 +24,21 @@
      * @var int
      */
     public int $sorting;
+
     /**
-     * CSS Files to load.
-     *
-     * @var string[]
-     */
-    public array $css = [];
-    /**
-     * JS Files to load.
-     *
-     * @var string[]
-     */
-    public array $js = [];
-    /**
-     * The image to use as a logo.
-     *
-     * @var string|null
-     */
-    protected ?string $image = null;
-    /**
-     * The template file to load.
+     * JSON representation of an API Blueprint.
      *
-     * @var string
+     * @var object
      */
-    protected string $template;
+    protected object $object;
+
     /**
      * The base data of the API.
      *
      * @var array<string, mixed>
      */
-    protected array $base_data;
+    protected array $base_data = [];
+
     /**
      * JSON object of the API blueprint.
      *
@@ -66,4 +51,39 @@
      * @var BasicStructureElement[]
      */
     protected array $base_structures = [];
+
+    /**
+     * Parse base data
+     *
+     * @param object $object
+     */
+    protected function parse_base_data(object $object): void
+    {
+        //Prepare base data
+        if (!is_array($object->content[0]->content)) {
+            return;
+        }
+
+        $this->base_data['TITLE'] = $object->content[0]->meta->title->content ?? '';
+
+        foreach ($object->content[0]->attributes->metadata->content as $meta) {
+            $this->base_data[$meta->content->key->content] = $meta->content->value->content;
+        }
+
+        foreach ($object->content[0]->content as $value) {
+            if ($value->element === 'copy') {
+                $this->base_data['DESC'] = $value->content;
+                continue;
+            }
+
+            $cat = new Category();
+            $cat = $cat->parse($value);
+
+            if (($value->meta->classes->content[0]->content ?? null) === 'dataStructures') {
+                $this->base_structures = array_merge($this->base_structures, $cat->structures);
+            } else {
+                $this->categories[] = $cat;
+            }
+        }
+    }
 }

src/PHPDraft/Out/TemplateRenderer.php → src/PHPDraft/Out/HtmlTemplateRenderer.php

@@ -31,8 +31,36 @@
 use Twig\TwigFilter;
 use Twig\TwigTest;
 
-class TemplateRenderer extends BaseTemplateRenderer
+class HtmlTemplateRenderer extends BaseTemplateRenderer
 {
+
+
+    /**
+     * CSS Files to load.
+     *
+     * @var string[]
+     */
+    public array $css = [];
+
+    /**
+     * JS Files to load.
+     *
+     * @var string[]
+     */
+    public array $js = [];
+    /**
+     * The image to use as a logo.
+     *
+     * @var string|null
+     */
+    protected ?string $image = null;
+    /**
+     * The template file to load.
+     *
+     * @var string
+     */
+    protected string $template;
+
     /**
      * TemplateGenerator constructor.
      *
@@ -109,41 +137,6 @@ public function get(object $object): string
         ]);
     }
 
-    /**
-     * Parse base data
-     *
-     * @param object $object
-     */
-    private function parse_base_data(object $object): void
-    {
-        //Prepare base data
-        if (!is_array($object->content[0]->content)) {
-            return;
-        }
-
-        $this->base_data['TITLE'] = $object->content[0]->meta->title->content ?? '';
-
-        foreach ($object->content[0]->attributes->metadata->content as $meta) {
-            $this->base_data[$meta->content->key->content] = $meta->content->value->content;
-        }
-
-        foreach ($object->content[0]->content as $value) {
-            if ($value->element === 'copy') {
-                $this->base_data['DESC'] = $value->content;
-                continue;
-            }
-
-            $cat = new Category();
-            $cat = $cat->parse($value);
-
-            if (($value->meta->classes->content[0]->content ?? null) === 'dataStructures') {
-                $this->base_structures = array_merge($this->base_structures, $cat->structures);
-            } else {
-                $this->categories[] = $cat;
-            }
-        }
-    }
-
     /**
      * Get the path to a file to include.
      *