Better to combine basePath with paths in swagger file or keep them separate? (Visualization issue!)

So I'm noticing an issue with both SmartDocs and Swagger UI visualization tools regarding basePath & paths.

If I consolidate my APIs down to the lowest common denominator and make that my basePath (say /v1/cars) and start my paths + verbs as normal, I get incomplete looking visualization dropdowns like "/" or "/{id}" versus html dropdowns like "/v1/cars" and "/v1/cars/{id}" which looks better!

So do folks drop the basePath (it is optional) on their published swagger specs so it visually looks better or do they keep them broken apart but put up with confused developers?

Or does someone know a way to visually combine them while leaving the swagger spec alone?

Thanks,

-Jeff

0 3 1,232
3 REPLIES 3

So, I've gone with the option of removing the basePath keyword from my Swagger files and instead, I put a comment in the bottom of my GFM Description regarding the basePath and what it really is.

(EDIT: Adding example images)

Here's what I'm talking about as far as absolute vs relative URI endpoints & helping 3rd party developers understand your swagger files quickly.

1. Absolute URI endpoints:

9167-absolute-uri-endpoint-paths.png

Which in my opinion are far more readable!

2. Relative URI Endpoints:

9168-relative-uri-endpoint-paths.png

While they're technically accurate if you've got a basePath defined of "/v1/catalogs" you end up with relative URI endpoints which I think causes some confusion.

Figured I'd give some pictures to help explain my dilemma. 🙂

-Jeff

Jeff, I liked your question, but I didn't have a solid opinion one way or the other.

Thanks Dino! Yeah, this is definitely more of a developer on-boarding thingy and not necessarily a technical Apigee related question. I just know that developer portals that are simple, easy to understand and aren't too clutter will lead to faster usage & adoption of our APIs.