Some places I hit friction while exploring: - It was tough to close the "Test request" window. - I wasn't sure how to interact with the product without more trial and error.
Two suggestions I thought might be useful: 1. Add OpenAPI linting to the editor. Right now it works with invalid specs as long as long the JSON is formatted correctly. 2. Allow users to import an example spec from the initial Getting Started page. (The editor is a good home for it, too, but I would have found it sooner).
Disclosure: I'm a Redocly employee, but have managed doc projects in a variety of tools. This is a neat approach! Great work and congrats.
> It was tough to close the "Test request" window. - I wasn't sure how to interact with the product without more trial and error.
Ah, this is great feedback. We can make it more clear with a button, as well that you can hit escape.
> Add OpenAPI linting to the editor. ah, great idea. will triage this and get this in.
> Allow users to import an example spec from the initial Getting Started page. In the getting started page we have "import url, paste swagger" & "petstore + tableau + cmc" examples to import by clicking.
Did you mean to add it to the editor?
Ah that's very cool, back in the day I always would install redocly instead of swagger UI, great work with Redocly :)
Again I really appreciate the kind words and your time.
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 me. Does this handle recursive schemas (which can never be fully expanded)?
If you have a chance please reach out to marc@scalar.com and we can start working on some improvements.
Ah that's great feedback!
As for the rendering of the schemas, we have a pull request in draft from this morning! hopefully will be done ASAP
Nit: don't call them Swagger files — OpenAPI has been around long enough to warrant recognition.
you're right! I updated the description[1] to include OpenAPI since people do still loog for swagger :)
[1] Beautiful API references from Swagger/OpenAPI files
> The OpenAPI Specification, previously known as the Swagger Specification is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services.
I found the name weird, since I'm only used to open API. It's when your mode of access is obscured, like poking physical hardware, or triggering code through HTTP or other generic protocols, that one needs to actively describe the API to make it "open".
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!
- modern design - deeply integrated rest api client - free hosting with an apidocumentation.com subdomain - offline search with fuse.js - and more!
We also have a full api docs platform, where you can: - have full customization so you get on brand docs - subdomain & custom domain hosting
We put a lot of time to make these products integrated, cause what we see right now with current solutions is deep fragmentation.
I agree on most tools making it worse, long term we aim to make this better with a git sync feature and docstring parsing! :) -
> 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!
Mintlify's editing experience is powered by mdx files that live alongside your code which makes it super easy for developers to edit docs if that is of interest to you.
> The space is crowded with many similar products.
Totally agree. This thread is proof that there is a lot of innovation happening here and a lot of different angles & approaches. It's exciting!
we are cross the technical documentation spectrum solution, doing anything from end-user/dev API/guides to internal management of technical knowledge.
let me know if you'd like a demo, I'm the founder.
Docusaurus integration is going to be the next one we do! Sign up and we can notify you there, on our discord or of course when we push it to github :)
Also, I highly appreciate redoclys starter template which tackles more serious topic about developing API first with reusable components instead of writing everything in one big file is is nightmare.
Very customizable in my experience (working with it with .NET SwaggerGen tooling).
Thanks so much for your thoughtful feedback and giving our first open sourced tool a try. Please don't hesitate to reach out here or email me directly at marc@scalar.com if you have any feedback or if I can help you in any way shape or form with your API.
That said, I don't just use Open API for documentation. I use it to generate clients and servers so that my customers can easily upgrade versions or generate them themselves. Are there any plans to formulate examples from those generated clients? That, today, has to be hand annotated if you want the custom examples (beyond REST) to appear in the API documentation.
Our plans are to make it easier to integrate with existing SDK generation tools so you can use them inside of our API docs.
https://www.speakeasyapi.dev/ is a really great platform and I think we can integrate with them and have examples from custom SDKs.
In the scenario with custom domains, we would have to rely on docstrings or comments depending on the language, I'll need more thought on that
Ah that's fantastic news about the custom views with Vue.js components.
Feel free to email me (marc@scalar.com) or join the Discord if you have any questions, need any features or bugs fixed please reach out :)
- The top bar disappears behind the navigation bar of Safari and there doesn’t seem to be a way to get it to reappear. - I tried to refresh the page to see if it would re-render and put the bar below the navigation bar, but I can’t pull down to refresh. Something is floating a window inside the window and I’m just pulling that around. - Tried clicking refresh in the nav bar and it didn’t fix the hidden top bar. - It’d be nice to be able to collapse the swagger editor in the reference view. Right now the left navigation is separated from the documentation and request tester on the right by 1/3rd of the screen (that is not being used at all).
Sidenote: we are going to be building a docusaurus plugin soon!
The language can be better throughout the repo so we will update that :) appreciate the comment
I hate redocly and swagger UI , and all of "enterprisey" offering on an open standard like OpenAPI.
I am also excited for another alternative, that feels modern!
Is it just another theme (not that we can’t use another theme)?
We just shipped adding headers + params interactive so people can add `x-api-key`
edit: why downvotes?
First of all we love open-source, we saw a huge opportunity to bring a modern design and some new features to swagger-ui & redocly.
Great question how we make money! We currently have: - a premium plan for hosting with a custom domain and guides
Our longer term plan is to build a dedicated REST API Client that is deeply integrated with all of our produts.
Feel free to join our discord, email me marc@scalar.com or sign up on scalar.com to stay updated :)
We debounce the input slight before parsing the spec to not block the browser
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.
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
Going to try to recreate this thought, maybe the page is slightly zoomed in on your device?
Also feel free to email me (marc@scalar.com) if that's easier :)
- Top bar is no longer hidden behind nav bar (usually). However, the bottom is cut off because of it. I didn’t even notice it at first, but everything below “Light mode” isn’t visible. It seems like it is fixed if I can scroll in such away that Safari hides the nav bar, but it’s finicky in allowing me to scroll far enough, or scroll on the correct frame, to cause Safari to hide the nav bar. I was able to get it stuck in a state where the top bar was hidden again and I couldn’t scroll to get it back. Refreshing the page made the top bar visible again.
- Pull to Refresh doesn’t work consistently. I can do pull to refresh if I can scroll in such a way the nav bar is hidden, but I can’t get the nav bar to hide itself consistently. I’m not a front end dev, so I’m not sure how much work it would be to fix the rendering of the window. It’s not as big of a deal to me since the top bar (the bar with `Scalar | Register | Sign In` etc.) is now visible.
Here’s a screencap of the first two items: https://file.io/uNQBUTmTTKul (Link will expire after 1 week). Sorry I couldn’t get an example of the top bar getting hidden or pull to refresh working. It was really difficult to reproduce.
- Being able to collapse the `Getting Started`/`Swagger Editor` frame would be nice (or to be able to control whether the viewer on the right is an additional tab next to the editor frame or it’s own distinct pane next to it), but that’s just personal preference. It would be helpful as someone who was consuming someone else’s API to isolate the features/content I need and hide those I don’t.
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
Will update the README to make this more clear