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 [email protected] 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).
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 ([email protected]) or just let us know in the comments :)
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 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.
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
[+] [-] BearEatingBees|2 years ago|reply
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.
[+] [-] marclave|2 years ago|reply
> 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.
[+] [-] melolife|2 years ago|reply
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)?
[+] [-] cameronrohani|2 years ago|reply
If you have a chance please reach out to [email protected] and we can start working on some improvements.
[+] [-] marclave|2 years ago|reply
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
https://github.com/scalar/scalar/pull/244
[+] [-] epse|2 years ago|reply
[+] [-] remoquete|2 years ago|reply
Nit: don't call them Swagger files — OpenAPI has been around long enough to warrant recognition.
[+] [-] marclave|2 years ago|reply
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
[+] [-] einpoklum|2 years ago|reply
> 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.
[+] [-] einpoklum|2 years ago|reply
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".
[+] [-] marclave|2 years ago|reply
[+] [-] bamazizi|2 years ago|reply
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!
[+] [-] marclave|2 years ago|reply
- 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! :) -
[+] [-] hahnbee|2 years ago|reply
> 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!
[+] [-] dragosbulugean|2 years ago|reply
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.
[+] [-] typosaur|2 years ago|reply
[+] [-] marclave|2 years ago|reply
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 :)
[+] [-] marclave|2 years ago|reply
[+] [-] maxloh|2 years ago|reply
[+] [-] cameronrohani|2 years ago|reply
[+] [-] majkinetor|2 years ago|reply
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.
[+] [-] GordonS|2 years ago|reply
[+] [-] marclave|2 years ago|reply
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 [email protected] if you have any feedback or if I can help you in any way shape or form with your API.
[+] [-] oooyay|2 years ago|reply
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.
[+] [-] desiderantes|2 years ago|reply
[+] [-] marclave|2 years ago|reply
Ah that's fantastic news about the custom views with Vue.js components.
Feel free to email me ([email protected]) or join the Discord if you have any questions, need any features or bugs fixed please reach out :)
[+] [-] Jka9rhnDJos|2 years ago|reply
- 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).
[+] [-] marclave|2 years ago|reply
Going to try to recreate this thought, maybe the page is slightly zoomed in on your device?
Also feel free to email me ([email protected]) if that's easier :)
[+] [-] snissn|2 years ago|reply
[+] [-] marclave|2 years ago|reply
Sidenote: we are going to be building a docusaurus plugin soon!
[+] [-] chrisweekly|2 years ago|reply
[+] [-] cameronrohani|2 years ago|reply
[+] [-] treve|2 years ago|reply
[+] [-] paulddraper|2 years ago|reply
[+] [-] marclave|2 years ago|reply
The language can be better throughout the repo so we will update that :) appreciate the comment
[+] [-] jamietanna|2 years ago|reply
[+] [-] revskill|2 years ago|reply
I hate redocly and swagger UI , and all of "enterprisey" offering on an open standard like OpenAPI.
[+] [-] marclave|2 years ago|reply
I am also excited for another alternative, that feels modern!
[+] [-] Aeolun|2 years ago|reply
Is it just another theme (not that we can’t use another theme)?
[+] [-] cpplinuxdude|2 years ago|reply
[+] [-] marclave|2 years ago|reply
We just shipped adding headers + params interactive so people can add `x-api-key`
https://github.com/scalar/scalar/pull/237
[+] [-] ushakov|2 years ago|reply
edit: why downvotes?
[+] [-] cameronrohani|2 years ago|reply
[+] [-] marclave|2 years ago|reply
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 [email protected] or sign up on scalar.com to stay updated :)
[+] [-] kyawzazaw|2 years ago|reply
[+] [-] marclave|2 years ago|reply
We debounce the input slight before parsing the spec to not block the browser
[+] [-] simonw|2 years ago|reply
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.
[+] [-] cameronrohani|2 years ago|reply
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.
[+] [-] marclave|2 years ago|reply
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
[+] [-] unknown|2 years ago|reply
[deleted]