search

mdwheele / laravel-openapi

Let's bring OpenAPI-driven routing, request and response validation to Laravel!
MIT License
20 stars 2 forks source link

Use Server Object to determine the Laravel Route prefix? #2

Open mdwheele opened 5 years ago

mdwheele commented 5 years ago

Currently, we hard-code the API prefix to be /api. This means that any specified Paths Object is prefixed with /api when registered with the framework. I kinda see 3 ways forward:

  1. Don't prefix anything. Don't do any magic. Use exactly what is in the Paths Object to determine routes.

    This is absolutely ship-able right now and might be better than doing a hard-coded magic prefix. It's also verbose and doesn't take advantage of the Server Object specification.

  2. Use a package configuration option (e.g. config('openapi.prefix')) to control the prefix and don't make OpenAPI responsible for that.

    This feels like a work-around for me and moves away from a primary goal of the project: to make the OpenAPI specification THE source of truth for an API. That said, it solves the problem and may be worth the trade-off in the short term?

  3. Use the Server Object to compute what the prefix path should be based on APP_URL and the first matching Server Object. The "diff" becomes the prefix.

    I like this, but we need this to be suuuuuuper obvious for a variety of hosting situations. For example, how does this behave when I have my API on a sub-domain or in a subfolder (e.g. api.example.org vs example.org/api vs example.org/path/to/api). In the case that we use APP_URL as our basis of "where the application is hosted", then we do a diff between server object and that configuration.

    For example, if APP_URL is https://example.org and we have a Server Object URL of https://example.org/api/v2, then the Route Prefix is /api/v2 and that's what we send to the framework. The problem is handling APIs that might be available from multiple URLs? I personally have NEVER had that use-case, but it's allowed by the specification as far as I can tell.

matthewtrask commented 5 years ago

This feels like a work-around for me and moves away from a primary goal of the project: to make the OpenAPI specification THE source of truth for an API. That said, it solves the problem and may be worth the trade-off in the short term?

I would think if this is configurable by the end-user, it's not a total workaround. Ideally, its updatable in the future so if its changed from /api to /api/v2, the client just needs to rerun the docs generation and the change will be reflected. The problem is if they support both examples for x amount of time. That can absolutely cause confusion

mdwheele commented 5 years ago

Hey @matthewtrask!

I would think if this is configurable by the end-user, it's not a total workaround. Ideally, its updatable in the future so if its changed from /api to /api/v2, the client just needs to rerun the docs generation and the change will be reflected.

Exactly! I guess my "strong opinion, held loosely" is that when they adjust from /api to /api/v2, they could be doing that in their OpenAPI specification and the package wouldn't need to provide this other Laravel configuration option outside of the spec. Ultimately, I just want to follow a path that "feels good" as a developer. What "feels bad" (to me) is that for a lot of folks I talk to getting into this stuff (that aren't doing code-gen and a bunch of fancy stuff) their specification is like this "bolt-on" thing that generates docs. I'd like it to drive more of the Application layer and buy some convenience!

The problem is if they support both examples for x amount of time. That can absolutely cause confusion

Do you have any ideas how someone would model this with OpenAPI? Would you have two Server Objects (one for each version) and just specify anyOf response bodies / request bodies that were the two versions?