Embed API Explorer for only part of an API

(Jason Shao) #1

I believe you used to be able to do this…

I would like to organize my API .yml files around larger units than parts of my documentation. In particular - I want to be able to segment out my documentation around type of user consuming the API

In the past, I think it was possible to sub-select paths inside the Swagger file…

(Jason Shao) #2

Or are others thinking about this differently? e.g. should I be decomposing my API into many smaller swagger files and then using the Hubs to compose them into a larger TOC?

We have a few odd cases where currently we have basically 2 sets of APIs to document (spread across a number of services and teams)

  • Consumer-facing APIs - generally live on a different domain, and are mostly HTTP GET ghetto RPC calls for tracking
  • B2B APIs live at api.company.com and have real auth, and REST semantics

The B2B APIs could be split across many Swagger files with the same basePath… but that feels a bit icky…

(Einnes) #3

This feature was removed from the ‘easy to use’ set up where you could choose a piece of your API from a Swagger file from a drop-down. I agree that you could want to have docs around different endpoints not every last thing in a single file. I think maintaining tons of little files would be a pain and also when you take the whole file using the new set up it adds a bunch of stuff that an end user won’t necessarily want, making the grab just one piece feature really cool and valuable. You can still use this feature but you have to do it manually. What you do is:

  1. In Design mode, make a new page (for this walkthrough).
  2. In the Page Type area, choose OpenAPI.
  3. You should see a third row under the Page Settings section that begins with a little icon that is a square with an arrow pointing out of it up and to the right. In the box to the right of the icon, you have to manually enter the piece of your API you want to work with. The best way to do this is with a self-referential link, so your link is going to generally look like: “.//nameoffile.oas2.yml#/paths/-path-to-your-endpoint

To get the path, the way it looks like it’s done is for anything past your base path you denote a slash with “~1” and then you put the name of the section of the endpoint, and so on until you have represented your endpoint. At the end you put a slash, and what kind of request you’re making.

So as an example, say my endpoints from a file have “rest-ww.telesign.com” as the base path. And say my complete endpoint is “https://rest-ww.telesign.com/verify/sms” and I do post requests with it. I would write my file name link manually like this: “.//nameofmyfilewherethespecis.oas2.yml#/paths/~1verify~1sms/post”.

(Taylor Barnett) #4

The ability to reference specific operations in an easy to use way is something we want to bring back with the UI update in Next that we are working on now. Like @einnes said, it is possible now, but there’s a bit of manual work that has to be done to do it.

Unless there’s another good reason to, we don’t recommend decomposing an API into many smaller OAS files.

(Jason Shao) #5

Yeah - we did a couple quick exercises trying to use a shared file and multiple small OAS files, and it was… unpleasant…

(Jason Shao) #6

Really - I’d love to be able to do this per tag

Curious how other people organize - our Swagger seems to often have a lot of:

/entity-root/{name} type pattern, where our CRUD operations seem to map to

/entity-root/ (aggregate operations)

  • GET
  • POST

/entity-root/{name} (single entity operations)

  • GET
  • PUT

(I’m prejudiced against delete - we have been playing with lots of “status”:“inactive” - and whether we should model that as “do the delete and this is what we do with it” vs. “no you can’t delete”. In practice many of our APIs are event-submission and are backed with write-once storage

(Einnes) #7

What do you mean by per tag? If you mean like by POST / GET etc. you can, you would just put the right thing at the end of your path.

(Jason Shao) #8

I fixed the formatting above - basically I’m using tags to force grouping operations with slightly different paths - e.g. when I don’t want {id} to be a path parameter for aggregate operations. I think this is consistent with the examples from the Swagger spec.

(Jason Shao) #9

The 2nd scenario that I’d really like is to be able to filter the view of APIs in the autogenerated API explorer by tag. We have been playing with publishing separate hubs for different audiences (since we want a cohesive API platform, but have different types of integrations - partly for simplicity, and partly because - not everyone needs to know :wink: )

In that scenario I’d love to be able to easily publish:

hub1: tags=user,org,product,order
hub2: tags=user,org,profile,comment

or perhaps something like

hub1: filter:-profile, -comment
hub2: filter:+user,+org,+profile,+comment