Wow -- this is quite impressive. I'm delighted to see new offerings in this space. Kudos to the team!
I spent some time tinkering with the deployed preview (https://docs.scalar.com). I liked the thoughtful implementation around customizations / versioning, etc.
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.
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 me. Does this handle recursive schemas (which can never be fully expanded)?
I thought most of the alternatives used summary as a title and description as a body, which is how we've been writing it as well? Or am I out of wack here?
> 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.
Oh, forgot to mention that definition is a quote from the Wikipedia page about OpenAPI.
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".
Nice project. The space is crowded with many similar products. I couldn't get any primary differentiators between it and similar products already mentioned in this thread
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!
> 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!
I think the perfect use-case for this would be to embed it in a application, kind of like GraphQL Playground. Not sure I'd use it for user-facing documentation though, as it seems it doesn't have SSR or HTML output. Docusaurus Integration would be nice for that reason.
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 :)
Core redocly is free. To have any more serious customization, you need to pay significantly.
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.
There's Widdershins plus Slate too. Widdershins turns the OpenAPI specs into markdown, then Slate into HTML. The results look really nice, and the use of templates means it's easy to customise. I'm just finishing my first project with them now, and I'd happily use them again.
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.
This is really cool from a documentation standpoint and I love that there's an open source project encroaching in this space.
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.
Awesome! I recently encountered the need of expanding a Spring Boot Admin instance to offer OpenAPI docs for custom Spring Boot Actuator endpoints which are in their own group, hidden from the main API. As SBA requires custom views to be Vue.js components, this will probably fit pretty nicely.
I’m having a lot trouble navigating it on Safari for iOS on iPad.
- 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).
I’m on iPad, not iPhone. Sorry I can’t provide any feedback other than just some really crappy QA because I don’t do a lot of work with Swagger.
- 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.
If there's any specific things big or small we can do to help convince your enterprise employer please don't hesitate to reach out (marc@scalar.com) or just let us know in the comments :)
There's also postman.com, readme.com, buildwithfern.com, speakeasyapi.dev, useoptic.com, bump.sh along with countless others. It's a very, very crowded market
Many tools in this space have overlapping functionality, but have a lot of differences when it comes to building with them or consuming information from them.
The products take shape around opinionated solutions that are fundamentally different. So, while they "do the same thing", some have better tools for API authoring, some are more usable for non-technical stakeholders, some emphasize performance, some emphasize extensibility, etc.
A good analogy is cars. They all drive, but some have 4WD, some have truck beds.
Besides being huge fans of OSS software we really feel like packages like this only make sense in an Open Source environment. Licensing for developer tooling can't be restrictive or it's just a hassle to use. There great open source business models around support, service, and hosting.
I should have been more clear. I meant the video recording. In the video recording, the screenrecording is a little bit behind what the person is talking about.
Very nitpicking observation though.
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.
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.
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.
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.
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
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.