Combining API Docs with SDK Docs

(Agofer) #1

We are using Stoplight to create an external (and internal) documentation of our services APIs.
We also provide a JS SDK wrapping some of the API functionality for the use of JS Developers.
I can see several options:

  1. Add the relevant SDK methods descriptions on each of the API methods pages
  2. Add it as separate pages - either as MD or HTML pages, or as part of the hub pages.

I prefer to use the format used in the hub pages, but then I cannot share the same page with multiple hubs (e.g. for sharing content between internal and external hubs)
Any suggestions ?

(Taylor Barnett) #2

Hey @agofer, that’s a great question!

I would really suggest what you think is best for your users. If you think that they would go to a well labeled separate page (“JavaScript SDK” in the header), then I’d go for that route.

If you think they’d ignore that page, then it might be worth the work to try to include it on the API methods pages. The UI isn’t going to look as nice. This is because our API references don’t really build in a space for this since it is based on the OpenAPI Specification.

(Taylor Barnett) #3

For example, @einnes did a lot of custom work on her docs to include SDKs. You might get some inspiration from their docs:

(Agofer) #4

Looking at the example you sent - it seems like the direction I want to go for. That said, it seems it was done as pages within a single hub file (rather than a reusable HTML or MD file, which I can include in multiple hubs).
Of course I can create everything using HTML, but the format of the hub files is much more usable, flexible and appealing. Any plans to allow to create pages in this format for separate pages like you have for HTML or MD?
@einnes - Great job ! Is my assumption you used a single HUB page for all non API pages correct?
Thanks !

(Einnes) #5

Unfortunately they don’t have a single sourcing set up - I wanted to be able to reference a page and have it go multiple spots too since that’s pretty common. You have to manually copy pages if you want to do something like that.

I do not recommend mixing your SDK and API reference content. If you are doing a tutorial, fine. If you are like here are the API parameters, then that is all that page should be about. An SDK page would be similar if it’s reference - here’s the pieces and what they do. But you’d just use a regular page for the SDK since I don’t think there’s a way to do that in Swagger.

(Agofer) #6

@einnes Thanks for sharing your experience!

(Taylor Barnett) #7

You are correct that if the MD or HTML file is in the same project as the Hubs you are building, you can reference it multiple times in different Hubs. But we don’t have anything on the near term roadmap to do the same with pages in a Hub that aren’t powered by OAS, MD, or HTML.

We have considered having templates in the future for different files that could be used across projects. This would be an interesting use case to look into.

(Einnes) #8

It might be easy to offer the ability to make a menu choice just link to the page you’re referencing. But the link looks like a regular menu option that fits with the rest of the menu appearance.