Creating API Documentation is never a quick job. Despite decades of constantly trying to improve the scene, it can still take a huge amount of time to get something built from scratch.
If you're following the API Design-first workflow, then you're probably using OpenAPI to design the API before you start writing code, so you can then bung that through an OpenAPI-based documentation tool and get the rest of the way quite quickly.
If you're following the API Code-first workflow, you've probably built the entire codebase and are now faced with the daunting challenge of trying to bung a bunch of annotations throughout your codebase, unless you're lucky enough to be using one of the few web application frameworks that offer OpenAPI export by default.
Everyone else is left either manually creating things in some Markdown/HTML-based CMS, or setting up tools that can sniff traffic and turn that into OpenAPI, so it can then be shoved through one of those OpenAPI documentation generators and hosted somewhere.
Treblle API Documentation is a quick way to skip literally all of that. You don't need to write a bunch of OpenAPI, you don't need to annotate your codebase, and you don't need to set up a traffic sniffing proxy, because Treblle already is one.
I set up Treblle just to get more insight into how a freshly launched API was doing, checking on performance, and getting more transparency into failures and webhooks than logs could ever provide. It was a great surprise to see hosted API Documentation sitting right there, documenting all the endpoints in that API, without me having to do anything at all.
How Useful is this Documentation?
There's a wide scale of documentation quality.
At the very tippy top are hand-crafted OpenAPI-based docs, expanded upon by technical writers, constantly checked by OpenAPI-based contract testing, and full of examples that are validated against the scheme to guarantee they are right.
We don't all have time to create that wonderland, but the alternative is no documentation, and that's the worst possible outcome.
Instead of just giving up, or phoning it in with a list of URLs bunged into a random spreadsheet, or copying and pasting some examples into a Word document, why not have a constantly updated set of requests and responses that are guaranteed true because it's literally based off of your API traffic?
The documentation generated looks pretty bare bones at first, missing example request/response, code samples, etc. but then I started messing about with Alfred the AI assistant, and there's a lot more there than you might think.
I asked Alfred to "Create an example response for the certificates/:uuid" and it made a brilliant, and entirely valid example, without exposing any real data (don't want to be leaking PII or sensitive business data here).
I asked Alfred for sample HTTPie CLI command to fetch an order:
Ok, a little bit of work needs to be done to replace the values, but if I'm really trying to interact with this API there's an even easier way.
Treblle has baked in an "Open in Swagger" button, which will open the API in Swagger Editor. This lets me use the all powerful Try it Now functionality that has become the standard for having an API Console built into API documentation.
All I had to do was grab a real UUID from the API, pop it in the UUID box, then click Try it Now and I've got a real response coming back helping me test the logic.
What Could Be Done to Improve Treblle's API Docs?
Clearly this is an early release, and the majority of the work has been done to get the system all hooked up and working performantly and robustly, but I reckon there's some quick wins to be made on the UI for this documentation.
Three Column Layout
Everyone loves the classic Stripe API-esque approach to API documentation, with a nav bar on the left, parameter lists in the middle, and request/response examples and code samples on the right. This is kinda there with Alfred, but you have to ask each time, which makes it harder to scan for what you're looking for.
I'd take the list of parameters, try to determine anything I could like detecting its a UUID, date-time, email, etc, then tell the user that.
I'd add request and response samples to that right column, and rebuild them every time I notice a change in the schema.
It would use all the same logic, it would just have it all laid out nicely for the user when they get to the page, instead of having them go asking.
Try it Now
Building an API console certainly is not a simple task, but a future version of Treblle could bring the Try it Now into the right column of the hosted API documentation, to avoid sending users off to another page to figure out another tool.
Bring Your Own OpenAPI
A real power feature here would be letting users point to their own OpenAPI if they do have some. This could be watching a public URL (e.g.: https://example.com/api/openapi.yaml importantly,), or connecting a Git repository. However it's done, this would unlock some amazing functionality.
Firstly, it would improve the quality of the documentation by bringing in descriptions and extra validations that are hard to spot by sniffing.
Secondly, it would allow for detecting contract violations. If you have the OpenAPI the API team expect to be true, and you have the action traffic going through the API, you can spot mismatches and let the user know. This could ding the API Score, but more importantly, let the API team correct the OpenAPI to improve the quality and accuracy.
Overlays
An alternative to bringing your own OpenAPI would be to leverage Overlays, letting you patch in some long form descriptions and other changes (like Code Samples) to the existing OpenAPI it's generating,
[
Use OpenAPI Overlays Today
Overlays are a way to “patch” an OpenAPI document, by pointing to a specific part of it with a JSONPath, then using “actions” to update or remove parts of the document. Can this help you?
APIs You Won't HatePhil Sturgeon
Compared to Postman
The documentation produced reminds me a lot of the output Postman offered when they released their API documentation offering, which was produced off of a Postman Collection that you'd be manually keeping up to date from making requests, saving them, saving responses as examples, which would then show up in docs.
They've expanded upon that offering, with the ability to import OpenAPI, create a collection from it, then make docs from that. Then whenever you go and update the OpenAPI again it can suggest updates to your collection, which will trickle through to your docs.
All of that might be great if you're already using Postman, but for people just trying to get some simple API documentation up without clicking a million buttons it certainly isn't the ideal workflow.
Ideally you either sync OpenAPI up to your GitHub/GitLab repository (Apiary, Stoplight, etc.) or you skip the need to keep OpenAPI in sync by letting it run off your actual traffic.
Setting Treblle Docs Up
I mentioned getting them set up, so let's take a look at how.
Step 1: Sign up for Treblle and connect your API
Using the extensive list of integrations you can get an account, install a packager for your language/framework, pop your API tokens, and deploy.
I used the Laravel integration, which was basically just this:
composer require treblle/treblle-laravel
php artisan treblle:start
Update .env:
TREBLLE_API_KEY=YOUR_API_KEY
TREBLLE_PROJECT_ID=YOUR_PROJECT_ID
Register Treblle into your in your middleware aliases in app/Http/Kernel.php:
protected $middlewareAliases = [
// the rest of your middleware aliases
'treblle' => \Treblle\Middlewares\TreblleMiddleware::class,
];
Open the routes/api.php and add the Treblle middleware to either a route group like so:
Route::middleware(['treblle'])->group(function () {
Route::prefix('samples')->group(function () {
Route::get('{uuid}', [SampleController::class, 'view']);
Route::post('store', [SampleController::class, 'store']);
});
});
Step 2: View your API documentation without writing a single line of OpenAPI
Then when that's deployed, go for a click around your application to get the traffic going, and once you see some requests showing up in your project click on API Docs.
Just like that, you've got simple docs.
Summary
I'd recommend Treblle's API Documentation as answering the question: what is the easiest possible way to create API Documentation for an existing API.
It might not provide the most comprehensive API reference documentation possible out of the box, but the sheer ease of working with it, getting API documentation with literally zero effort, makes it a really valuable tool to have in your pocket.