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.

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.

> 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

... or you can use Claude with it's 100,000 token limit. I've had some very impressive results from Claude against long documents.

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.

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.

You can DIY this with LangChain OpenAPI chain: https://python.langchain.com/docs/use_cases/apis

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