vertx-openapi contradicts vertx-auth-oauth2

[shihb]

Describe the feature

Vert.x OpenAPI 5.0.8 application/x-www-form-urlencoded Support Paradox

Problem Background

The MediaType interface in Vert.x OpenAPI 5.0.8 only supports the following media types:

• application/json / application/json; charset=utf-8
• multipart/form-data
• application/hal+json
• application/octet-stream
• text/plain

However, it does NOT support application/x-www-form-urlencoded.

Meanwhile, the OAuth2 standard protocol (RFC 6749) specifies that token endpoints MUST use application/x-www-form-urlencoded format for submissions. This creates a contradiction:

• vertx-openapi: Does not support this media type, throws error on startup

I developed a token retrieval service using OpenAPI
Endpoint /api/sys/oauth/client type

     requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientToken'

When using vertx-auth-oauth2 to retrieve a token, it requires application/x-www-form-urlencoded format

• vertx-auth-oauth2 (OAuth2API): Follows the standard, uses application/x-www-form-urlencoded
  OAuth2API class

    headers.put("Content-Type", "application/x-www-form-urlencoded");
    final Buffer payload = SimpleHttpClient.jsonToQuery(form);

    // specify preferred accepted content type
    headers.put("Accept", "application/json,application/x-www-form-urlencoded;q=0.9");

    return fetch(HttpMethod.POST, config.getTokenPath(), headers, payload)

vertx-openapi contradicts vertx-auth-oauth2

Contribution

No response

[pk-work]

Hi @shihb, when Vert.x 5.1 is released, you will be able to add custom media types [1]. This would allow you to add support for application/x-www-form-urlencoded. But application/x-www-form-urlencoded is a very common media type, so it would make sense to have it in the standard.

Could you imagine to contribute this feature?

[1] 7e237cc

[shihb]

Hi @pk-work
Thank you very much for the clarification! I'd be happy to contribute this feature.
I have a few questions to get started:

1. Contribution guidelines: Could you please point me to the relevant contribution guidelines and coding standards I should follow?
2. Target version: Should I implement this for the current 5.0.8 version, or would it be better to wait for the 5.1 release?
3. Regarding the new design: I noticed that in version 5.1.0, all media type constants are marked as @deprecated. It seems like the design has changed to support custom media types, which I think is a great approach! This means that my issue will be resolved in the new version. so I'm not sure how I can help at this point.

I'm not entirely sure how I can best help in this situation. Could you advise on what would be most valuable for the project?
Thanks again for your guidance!

[pk-work]

Hi @shihb,

1. there are not much relevant guidelines. You need to have a valid ECA [1] and I'd like to see a good test coverage.
2. Yes, target version should be 5.1.
3. Yes, in 5.1 your issue is resolved, but you still have to implement your own ContentAnalyser [2] for application/x-www-form-urlencoded. Therefore it would make sense to implement this ContentAnalyser in this repository and make it available for everyone via a MediaTypeRegistration [3]. This MediaTypeRegistration can then be added to the MediaTypeRegistry.createDefault() [4] method.

Edit: In case you have access to discord, I can offer you a short sync call. There is a Vert.x discord server [5]

[1] https://www.eclipse.org/legal/eca/
[2]

vertx-openapi/src/main/java/io/vertx/openapi/mediatype/ContentAnalyser.java

Line 31 in 1efa73c

public interface ContentAnalyser {

[3]

vertx-openapi/src/main/java/io/vertx/openapi/mediatype/MediaTypeRegistration.java

Line 29 in 1efa73c

MediaTypeRegistration APPLICATION_JSON = new DefaultMediaTypeRegistration(

[4]

vertx-openapi/src/main/java/io/vertx/openapi/mediatype/MediaTypeRegistry.java

Line 30 in 1efa73c

static MediaTypeRegistry createDefault() {

[5] https://vertx.io/resources/

[shihb]

hi @pk-work
Thanks for the guidance!

I've completed the ECA registration, forked the repository, and joined the Vert.x Discord server (username: qingkong6130). I'll start implementing the feature when I have time.

Since I'm in China, there's a significant time difference between us. To avoid scheduling conflicts and ensure I can properly document our discussion, I'd prefer to communicate via text (GitHub or Discord messages). Please feel free to reach out to me on Discord if you have any requirements.

Looking forward to contributing!