Create an Open API spec for the current mock HTTP responses

FYI: the FieldForComponentSuggester service added in https://git.drupalcode.org/project/experience_builder/-/merge_requests/2... should provide a solid foundation one of the API responses we'll need (I have a component, what possible ways could the user assign a value to the component props?)

Any takers? Capturing the current mock requests + responses in this way sure would be beneficial, because we'd be able to evolve the OpenAPI schema, which would auto-document the evolution of the communication between client & server!

Looking through the handlers mock, I started the attached OpenAPI spec. It's still a work in progress, but I think it is a good starting point. Let me know what I missed and I can continue updating the spec.

Thanks, @pfrilling! 🤩

Could you convert that to an MR? 🙏 And could you add the SchemaValidationTest that verifies this Open API spec is itself valid? You can pretty much copy/paste it from @larowlan's work at https://git.drupalcode.org/project/decoupled_lb_api/-/commit/84bf1e54153... 😄

How do we validate this, and how do we keep it in sync with the reality? 🤔

That'd be amazing and what I'd hope for — because in a heterogeneous project like this (geographically, timezone-wise, employment-wise, availability-wise), that's really valuable!

Hi @pfrilling,
Can you brief me about the above merge request and how this issue needs further work?

@syeda-farheen:

1. The new test is failing:
   

   There was 1 failure:
   1) Drupal\Tests\experience_builder\Unit\SchemaValidationTest::testSchemaIsValid
   Failed asserting that an array is empty.
   

2. quoting @larowlan from #7:
   

   We can also write a test that loads the fixtures from UI and validates them AND uses drupalGet to load the controllers and validate them.

Clarified issue summary.

Given @syeda-farheen is not responding, assuming they're no longer working on this. Asking @TravisCarden to push this to completion, after he's done with #3458369: DDEV support for Cypress tests 😊

Importance/impactfulness of this confirmed one more at #3458683: Mock fixtures missing `field_data`.

Bumping to Critical.

This has been resolved and the API Spec test should be passing now.
> # 1 The new test is failing:

Do you have any examples for testing the fixtures against the spec? If not, I'll start researching how to make that happen.

I don't — I have zero experience with Open API 😅

But a quick search in @larowlan's decoupled_lb_api module reveals https://git.drupalcode.org/project/decoupled_lb_api/-/blob/1.x/tests/src..., whose assertDataCompliesWithApiSpecification() achieves exactly that :)

The tests that we add here should fail, because they should automatically identify #3458683: Mock fixtures missing `field_data`.

Tests have been added to confirm that the UI fixtures are validating against the Open API Spec. This should resolve #3.

3. Test that the fixtures in ui/src/mocks/fixtures match the OpenAPI spec, which proves the client (XB React UI) conforms to the OpenAPI spec

OMG that's exciting! 🤩 And it's passing tests, too! 🚀

#3460952: Implement add button for top level item (section) conflicted with this, merged in upstream and accepted upstream changes to the mocks.

This was causing increasing frustration for @jessebaker, @bnjmnm and @hooroomoo, and was slowing down @tedbow while working on #3446722: Introduce an example set of representative SDC components; transition from "component list" to "component tree", so I took this on.

This is now ready for final review.

@jessebaker & @bnjmnm FYI, based on the discussion y’all had yesterday, I prioritized this issue today. Result:

• 100% of XB API responses now are validated automatically
• Any occurrence of a lack of compliance with the spec now fails:
  • the Cypress E2E CI job (if the server does not comply)
  • 👆you can see that the error response is not quite as helpful as it could be in Cypress, will create a follow-up for that 👍
• the phpunit CI job (if the mocks do not comply)
  • 👆that happened after updating the OpenAPI spec to match the server, which is the Source of Truth currently
  • ✅ this proves that the OpenAPI spec now is used to keep everything in sync
• Fixing it causes the build to pass

Result: npm run dev works again:

Before

(Also currently live at https://project.pages.drupalcode.org/experience_builder/)

After

(but since making these screenshots, #3460952: Implement add button for top level item (section) landed, which changed the mock fixtures, so it'll look different now)

Assigning to @bnjmnm for review, since it's close to @jessebaker's workday.

But it still might make sense to delete the mocks+MSW functionality, if @bnjmnm and @jessebaker decide it's not relevant anymore.

However, if we do that, we should also get rid of the GitLab Pages CI job, which would remove the static UI demo.

If that's the case, then we should IMHO still land this first and then delete the mocks in a different issue. Because that'll make it easier to someday restore it if that'll ever make sense. I propose to repurpose #3458683: Mock fixtures missing `field_data` in that case.

@bnjmnm didn't get to this yesterday; so re-assigning to @jessebaker at his start of day 🤞

@jessebaker approved this 🥳 Hence reflecting that here by marking RTBC.

Note that the phpunit (next major) CI job is failing though:

There was 1 error:
1) Drupal\Tests\experience_builder\Unit\OpenApiSpecValidationTest::testSpecIsValid
Exception: Could not OpenAPI 3.0 schema at /builds/project/experience_builder/vendor/cebe/php-openapi/schemas/openapi-v3.0.json or /builds/project/experience_builder/vendor/cebe/php-openapi/schemas/openapi-v3.0.json.
/builds/project/experience_builder/tests/src/Unit/OpenApiSpecValidationTest.php:52
/builds/project/experience_builder/vendor/bin/phpunit:122
--
9 tests triggered 45 PHPUnit deprecations:

For those 45 deprecations, I already opened #3466534: Fix PHPUnit 11 deprecations when tested with Drupal 11 (it's happening on HEAD too). That 1 error I'll need to figure out here prior to merging.

Also, @jessebaker did point out that

7. If you want to run *all* tests locally, including the OpenAPI spec one: `composer require league/openapi-psr7-validator webflo/drupal-finder cebe/php-openapi --dev`

is not quite accurate. It's currently required. I did that because I want developers of XB to be aware of violations of the OpenAPI spec. But … actually doing that conditionally (if those deps are installed) would be better.

Did that in https://git.drupalcode.org/project/experience_builder/-/merge_requests/5... 👍

RE the error described in #26:

• on 10.x, cebe/php-openapi is getting installed: https://git.drupalcode.org/project/experience_builder/-/jobs/2359889
• … but not on 11.x

WTAF?!

Well … AFAICT the reason is Drupal 11 requires Symfony 7, and that is not yet allowed by cebe/php-openapi: https://github.com/cebe/php-openapi/pull/203 + https://github.com/cebe/php-openapi/pull/202.

That last link points to https://github.com/DEVizzent/cebe-php-openapi, which … is a fork because the original is no longer maintained 🤷‍♂️

• original: https://packagist.org/packages/cebe/php-openapi, 10.3M installs
• fork: https://packagist.org/packages/devizzent/cebe-php-openapi, 1.97M installs

So obviously the ecosystem is switching over. Did the same here.

Bonus: upgrade to OpenAPI 3.1 (released in Feb 2021), which was a major motivator for people forking that library! 🎉

So I just read https://lornajane.net/posts/2020/whats-new-in-openapi-3-1 and found several things that I could not get to work to be fixed now! So refined the OpenAPI spec some more.

I noticed that the examples visible in GitLab's OpenAPI visualization at https://git.drupalcode.org/issue/experience_builder-3450308/-/blob/34503... were off … so I tried improving that using https://editor.swagger.io/, but that does not support OpenAPI 3.0.

Then found https://editor-next.swagger.io/ and … that works perfectly. With live updating, even!

I did not make material changes since @jessebaker approved this, I only made it not get in the way (see #27) and pass tests against Drupal 11/Symfony 7 (see #26 and #28). And then I added finishing touches (see this comment.)

So: merging 🚢

Actually, the title has been inaccurate all along 😅 Fixed that, and created a follow-up for doing that other part: #3466555: Also validate request bodies against the OpenAPI spec.