Hacker News new | ask | show | jobs
by simonw 979 days ago
Looks very JavaScripty.

I like my API documentation to mainly be boring old static HTML, with any interactive features using JavaScript layered over the top.

Using HTML makes it faster to load, easier to get it indexed by search engines, easier to save and run offline and easier to process through LLM tools like ChatGPT and Claude.
2 comments
cameronrohani 979 days ago
Can certainly respect that approach!

This is definitely a more Javascript heavy approach but without JS you can't get some nice quality of life features like the embedded REST API client for experimenting with endpoints.

As for LLMs we have had the best experience passing them Swagger files directly and not relying on an intermediate parse to text.

link
majkinetor 979 days ago
Having a REST API client for experimenting in a documentation turns out to be wishful thinking. Its a toy compared to full-blown testing client such as thunder or bruno. Its probably for the best to save the effort and just make documentation itself better and more customizable.
link
simonw 979 days ago
That's what I meant by "interactive features using JavaScript layered over the top" - you can still have the embedded REST API client behaving exactly the same, but if you load the page without JavaScript (e.g. a search engine crawler) you get the rest of the content as HTML.

Great point about feeding the Swagger files straight into the LLM.

link
ushakov 979 days ago
> Great point about feeding the Swagger files straight into the LLM.

That doesn't scale though. Notion OpenAPI doc is more than 6k lines. You will have to resort to some splitting techniques or using vector stores

link
simonw 979 days ago
... or you can use Claude with it's 100,000 token limit. I've had some very impressive results from Claude against long documents.
link
jon-wood 979 days ago
As an aside, this is how ChatGPT’s plugin support works, and I always find it slightly mind blowing. You give it some OpenAPI docs, and a some brief instructions on what the API is good for, and then off it goes and uses it.
link
ushakov 979 days ago
You can DIY this with LangChain OpenAPI chain: https://python.langchain.com/docs/use_cases/apis
link
marclave 979 days ago
appreciate the comment!

the hosted version has SSG :) but we can probably do an ssg build option... going to triage that and maybe get that in over the weekend with some redbulls

link