API/SDK Documentation

[simenandre]

Hello! 👋

In most cases, developers are looking to use one of the SDKs. Many of the other API businesses out there expose their SDK documentation along with quick start guides and examples. And I think from a developer point of view, it would be nice to add that to this repository too.

I really like Pulumi's setup. They utilize a build script that collects API documentation from each of the repositories and adds those Markdown-files to their website. Maybe something like that would work here as well?

I wouldn't do exactly like Pulumi since they convert comments from source code to Markdown in the same sequence as they are pulling them. In Swedbank Pay's case, I would suggest that every official SDK have a standardized docs/ folder. This would serve as documentation for the developers that find it directly on Github, but also could be rendered in HTML under developer.swedbankpay.com. I would have README.md that would be the introduction to the SDK (also for the HTML counterpart) and typical quickstart files and examples altogether.

I'd say something like this could work:

├ docs/
├── README.md
├── api/
│   ├── this-class.md
└── QUICKSTART.md

From this, a simple script could populate SDK documentation. Pulling down all docs/ folders periodically (or with every SDK release). Alternatively, one could deploy SDK documentation from every SDK. However, this would probably cause more headache.

What do you think of the idea?

[asbjornu]

This is a great idea and something we actually have on our Jira backlog. 😃 Thanks for describing a possible solution – it sounds indeed like something that could work for us.

[simenandre]

👋

During the summer, I implemented a version of this flow on tabetalt/docs. The design consists of a plugin, namely docusaurus-multiple-docs, I had to build this library.

A few thoughts after having used this setup a while:

You'll get locked into docusaurus with it, which could be fine, but I like the least amount of specialized files in each of the repositories. We had to make some extra functionality to retrieve CHANGELOG (which is something we need at Tabetalt).

If I was going to do it all over again.

1. I'd rather make a simplified configuration (maybe inspired by discovery documents) eg.:

# sdk.yaml
name: Typescript
version: 1.3.4
repository: https://github.com/.../...
links:
 - name: Getting started
   file: getting-started.md
 - name: Changelog
   file: CHANGELOG.md
...

2. I'd rather have a build step (eg. Github Actions-step) that pulls down latest versions of all the packages and retrieved the configurations (from above 👆), combine them and potentially transform that simple configuration to Docusaurus (or whatever).

It would probably be less work than I spent on Tabetalt's setup and it could be used in a template as well. Furthermore, if you ever decided to go this route, I'd be interested in building it again and subsequently update Tabetalt's setup.