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.
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.
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
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