Skip to content

Stabilized render of REST HTML #1896

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Feb 16, 2023
Merged

Stabilized render of REST HTML #1896

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d2d60b7
Stabilized render of REST HTML
Steveb-p Feb 15, 2023
52a8db0
Stabilized render of REST HTML
Steveb-p Feb 15, 2023
5fc66db
Stabilized render of REST HTML
Steveb-p Feb 15, 2023
ffc41cd
raml2html: Upgrade to PHP 7.4 (#1898)
adriendupuis Feb 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2,840 changes: 1,404 additions & 1,436 deletions docs/api/rest_api_reference/rest_api_reference.html
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion tools/raml2html/composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
}
],
"require": {
"php": "^7.2",
"php": "^7.4",
"symfony/console": "^4.2",
"raml-org/raml-php-parser": "dev-master",
"twig/twig": "^2.0",
Expand Down
2 changes: 2 additions & 0 deletions tools/raml2html/src/Application.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
use EzSystems\Raml2Html\Command\LintTypesCommand;
use EzSystems\Raml2Html\Generator\Generator;
use EzSystems\Raml2Html\RAML\ParserFactory;
use EzSystems\Raml2Html\Twig\Extension\HashExtension;
use EzSystems\Raml2Html\Twig\Extension\RenderExtension;
use Symfony\Component\Console\Application as BaseApplication;
use Twig as Twig;
Expand Down Expand Up @@ -63,6 +64,7 @@ public function load($class): ?MarkdownRuntime {
return null;
}
});
$this->twig->addExtension(new HashExtension());
}

return $this->twig;
Expand Down
35 changes: 35 additions & 0 deletions tools/raml2html/src/Twig/Extension/HashExtension.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<?php

/**
* @copyright Copyright (C) Ibexa AS. All rights reserved.
* @license For full copyright and license information view LICENSE file distributed with this source code.
*/
declare(strict_types=1);

namespace EzSystems\Raml2Html\Twig\Extension;

use RuntimeException;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class HashExtension extends AbstractExtension
{
private $hashes = [];
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it possible for us to force higher PHP version here and use its features, like strict type in this case? I'd go for the latest PHP 8.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alongosz I moved to PHP8.1+ in #1871. I can take care of this there.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically possible, it's an internal tool.

Well, copied from an open source library afaik.

However, I'm not sure what versions of PHP our doc team have, and I'm not sure if we can just force PHP 8. PHP 7.4 would be more suitable?

Copy link
Contributor

@adriendupuis adriendupuis Feb 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I propose #1898 as quick fix for PHP 7.4 as it doesn't work with 7.2 anymore.

For PHP 8.1+, I'll make a survey.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're all good with at least PHP 8.1

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's merge this w/ 7.4 and I'll continue my 8.1 PR afterward.


public function getFunctions(): array
{
return [
new TwigFunction('hash', function (string ...$values): string {
$hash = hash('sha256', json_encode($values));

if (isset($this->hashes[$hash])) {
throw new RuntimeException('Hash is generated twice for ' . json_encode($values));
}

$this->hashes[$hash] = $hash;

return $hash;
}),
];
}
}
5 changes: 2 additions & 3 deletions tools/raml2html/src/Twig/Extension/RenderExtension.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,7 @@ public function getExamplesTabs(array $responseBodies): array

/** @var \Raml\Body $body */
foreach ($responseBodies as $body) {

if (!empty($body->getExample())) {
if (!empty($body->getExamples()) && !empty($body->getExample())) {
$tabs[] = $this->getSchemaFormat($body->getMediaType());
}
}
Expand All @@ -85,7 +84,7 @@ public function getExamplesBody(array $responseBodies): array
foreach ($responseBodies as $body) {
$schemaFormat = $this->getSchemaFormat($body->getMediaType());

if (!empty($body->getExample())) {
if (!empty($body->getExamples()) && !empty($body->getExample())) {
$examples[$schemaFormat][] = $body->getExample();
}
}
Expand Down
3 changes: 2 additions & 1 deletion tools/raml2html/themes/default/example-modal.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,12 @@
{% for body in example %}
{% set margin = example|length > 1 and loop.index == 1 ? 'mb-4' : '' %}
{% set border = loop.index > 1 ? 'border-top' : '' %}
{% set outer_loop = loop %}
{% for body in example %}
{% set margin = example|length > 1 and loop.index == 1 ? 'mb-4' : '' %}
{% set border = loop.index > 1 ? 'border-top' : '' %}
<div class="position-relative {{ margin }} {{ border }}">
{% set clipboardId = type ~ '_' ~ uuid() %}
{% set clipboardId = hash(type, outer_loop.index, loop.index, tabId) %}
<p class="mb-0 icon icon--copy-clipboard">
<i class="material-icons-outlined clipboard"
data-toggle="tooltip"
Expand Down
2 changes: 1 addition & 1 deletion tools/raml2html/themes/default/example.html.twig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
{% set margin = example|length > 1 and loop.index == 1 ? 'mb-4' : '' %}
{% set border = loop.index > 1 ? 'border-top' : '' %}
<div class="position-relative {{ margin }} {{ border }}">
{% set clipboardId = type ~ '_' ~ uuid() %}
{% set clipboardId = hash(type, tabId, loop.index) %}
<p class="mb-0 icon icon--copy-clipboard">
<i class="material-icons-outlined clipboard"
data-toggle="tooltip"
Expand Down