21–30 of 74 posts
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.
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.
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.
Earlier quoted context omitted.
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.
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
Earlier quoted context omitted.
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.
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.
I'm interested in new offerings in this area, as all of the existing options are pretty janky. A couple of thoughts: Operation.summary is typically derived from the documentation for an API operation, and should not be used as the operation title as it is far too long. Instead use the operationId and path. I can't get it to render schemas for a bunch of my OpenAPI documents, and there are no error messages to guide m…
This is great feedback that we'd love to take a closer look at. If you have a chance please reach out to marc@scalar.com and we can start working on some improvements.
How does this differ from stoplight.io? Is it just another theme (not that we can’t use another theme)?
Looks like a similar solution to https://github.com/stoplightio/elements - will give this a whirl some time!
I prefer self-hosted or internally managed product only! However, what's really hard to find is a solution that integrates with technical & business documentation stacks. If anyone knows any good products please please please share...
I feel stuck using a frustrating product like Confluence and tried a few open source alternatives but couldn't get conviction to switch (bad vs worse). We've been trying 'swimm.io' but everybody has to go out of their way to incorporate it into their workflow, sooo nobody really using it! It doesn't help that most of us use vim/neovim and not IDEs ... majority of engineers don't really like the documentation part of their work and most tools make it worse!