Also validate request bodies against the OpenAPI spec

#3450308: Create an Open API spec for the current mock HTTP responses is in.

I had previously assigned #3450308: Create an Open API spec for the current mock HTTP responses to @TravisCarden. Now that that foundation is in, I bet this will be right up his alley 😊

@lauriii just opened #3469850: [PP-1] Occasional PHP warning when refreshing XB this morning. This issue:

1. would at minimum make writing a test for that trivial
2. likely will surface that same problem through our existing E2E tests

See #3469850-2: [PP-1] Occasional PHP warning when refreshing XB for details.

#7: totally possible!

Note that #3450308: Create an Open API spec for the current mock HTTP responses introduced the use of that validation library, and it tried to follow the examples set by @larowlan's decoupled_lb_api module:

• https://git.drupalcode.org/project/decoupled_lb_api/-/blob/1.x/tests/src...
• https://git.drupalcode.org/project/decoupled_lb_api/-/blob/e991d78949988...
• https://git.drupalcode.org/search?search=OpenApiSchemaTrait&nav_source=n...

#8: Yay! 😄 I created a MR for your branch, so that CI runs and reviewing the code becomes possible. Posted an initial high-level review, and this is looking superb! 👏 For one of the @todos, I talked to @balintbrews who's worked on #3461431: Improve client side error handling that ties in to your observation 👍

Also, zooming out — I bet that by the time you're done with this, you'll have an idea/opinion of how to:

• expand /openapi.yml, because it is incomplete still
• maximally use OpenAPI validation to our advantage — both for making sure the front-end and back-end end up in a more consistent place, as well as preparing the XB codebase for swift evolution after #3454094: Milestone 0.1.0: Experience Builder Demo — because all XB API routes are currently very ad-hoc (in terms of URL structure, logic, etc.)
• document where the exact cut-off lies of where OpenAPI validation ends (i.e. request/response shape validation) and "real" validation (i.e. content/config entity validation that inspects the actual values used, the "foreign keys" if you will)

Could you please create issues for what you believe should be the next steps for XB's use of OpenAPI?

Would you be interested in not only documenting what you believe should be the best practices, but also pushing forward XB's use of OpenAPI? (Totally fine if the answer is negative!)

#3470528: Alphabetize `openapi.yml` fields is in 👍

@traviscarden I bet #3470995: OpenAPI validation errors must be provided as a JSON response happens to be related to the mysterious bit you asked about yesterday, and which you've currently got this for:

+    // Ignore an empty JSON response.
+    // @todo When/why does this happen? Is it actually an error condition?
+    if ($response->getContent() === '{}') {
       return;
     }

🤞

#17 Woah! No need for that next time, although the intent is very much appreciated! 😄

Several CI jobs are failing, so this cannot be RTBC … 😅 See https://git.drupalcode.org/project/experience_builder/-/pipelines/268587.

I'll push this across the finish line.

This represents a solid unit of work, and request bodies now are being validated. If I change the spec for the "preview" route to expect something nonsensical, then I do get the expected error now 👍

@tedbow RTBC'd in #19 but didn't approve the MR. @hooroomoo suggested the JS changes this MR makes, and they're trivial. So: rather than waiting for them clicking stuff in GitLab, going ahead and merging this, because @traviscarden has pointed out this has been painful to keep resolving conflicts for. (Plus, the next MR that touches openapi.yml is already awaiting: #3467843: Back-end route to allow logging from the UI.)

Next steps:

1. We get errors now for invalid request bodies … but not yet in a very friendly way — see #3470995-2: OpenAPI validation errors must be provided as a JSON response — I think that issue is a logical next step after this. (That unfriendliness is pre-existing: this MR did not introduce that!)
2. Can you create a follow-up issue to document the routes that do not yet have request bodies documented in openapi.yml? 🙏 (i.e. for the @todo that @tedbow commented on over at https://git.drupalcode.org/project/experience_builder/-/merge_requests/2...)
3. It's pretty clear that you have opinions about how we should push this area ("OpenAPI" and all adjacent things) forward further. While working on this MR, you've noticed that several times another MR conflicted with this one. I think it'd make sense to have a person overlooking this crucial area to keep the front-end and back-end code + folks in sync. It will undoubtedly also help future contributors onboard. Plus, this API will evolve — the /xb-components controller returns a lot of cruft 💩 right now. It's "good enough" for now, but it won't remain that way: as the number of installed components grows and/or we're adding too much information to it, that route in particular will hit its limits (… and it seems that literally in the last 24 hours we might've hit that point: #3471070: `/xb-components` takes multiple seconds when *many* SDCs are present 😅).

   So … I'd like you to own that/be the overseer. 🤞🙏 If you agree, please create a new issue that contains:

   diff --git a/CODEOWNERS b/CODEOWNERS
   index 56207fd7..0fede359 100644
   --- a/CODEOWNERS
   +++ b/CODEOWNERS
   @@ -17,6 +17,13 @@
    # Hybrid side.
    #
    
   +[OpenAPI] @traviscarden
   +/openapi.yml
   +/src/EventSubscriber/ApiMessageValidator.php
   +/tests/src/Traits/OpenApiSpecTrait.php
   +/tests/src/Unit/OpenApiSpecValidationTest.php
   +/tests/src/Unit/UiFixturesValidationTest.php
   +
    [semi-coupled theme engine] @bnjmnm @hooroomoo
    /src/Theme/XBThemeNegotiator.php
    /themes/engines/semi_coupled/
   

   😊

Very glad to see this land! 🚀😄

Reverting to Patch (to be ported) to signal this landed, but follow-up issues are still needed. Assigning to @traviscarden for that.

#21:

1. @traviscarden has AFAIK started on #3470995: OpenAPI validation errors must be provided as a JSON response 👍
2. I cannot find this follow-up yet among https://www.drupal.org/project/issues/search/experience_builder?issue_ta...
3. @traviscarden did this: #3471303: Add TravisCarden to `CODEOWNERS` for OpenAPI 🚀

No, I wasn't looking for that.

The follow-up I requested is for documenting the expected request bodies for routes that do not have that defined yet. That's independent of generating JSON responses instead of plain text PHP stack traces, which is what #3470995: OpenAPI validation errors must be provided as a JSON response is for.

But I do think it makes sense to cover "missing request bodies" as part of #3472584: Add missing request body schemas to `openapi.yml`. Clarified that at #3472584-5: Add missing request body schemas to `openapi.yml`.

Ah, great! 😄 You definitely made me scratch my head! 😜