Scalar: Generate interactive API documentations from Swagger files | Hacker News Reader

Scalar: Generate interactive API documentations from Swagger files

github.com

225 pointsagmiklas70 comments

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.

Appreciate the kind words, and the suggestions!

> 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)?

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.

After some more experimentation it looks like you don't support allOf/anyOf/oneOf which seems like a pretty big hole.

our swagger parser isnt perfect yet, appreciate this comment and I added it to triage. We will get this fixed quick

Swagger or OpenAPI parser?

Swagger + OpenAPI v3/v3.1 parser, sorry I needed more coffee was up way too late this week with launch

Will update the README to make this more clear

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?

hey! co-founder here, appreciate your comment.

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

This so nice. Well done! I'll surely give it a try. I appreciate the fresh theme in particular.

Nit: don't call them Swagger files — OpenAPI has been around long enough to warrant recognition.

co-founder here, we appreciate the kind words!

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

Some context for the less-informed (like myself):

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

this is great context, it definitely can sometimes be confusing with the dual usage and sometimes not using either-or. :)

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!

hey! ceo & co-founder here, some key differentiators. It definitely is a busy space, but we feel like there's some key differentiators:

- 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! :) -

hey @bamazizi, I think you are looking for archbee.com

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.

hello! Cofounder of mintlify.com here.

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

Appreciate the comment!

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 :)

ha love the username too :)

If you type my username + .com, you'll know why ;)

very cool :)

Aren't Redocly and Swagger UI open-source too?

They sure are. In hindsight the title is a little ambiguous but OSS is the standard for this type of developer tooling.

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.

RapiDoc is quite nice and built with Lit so it sets up as just a custom web component.

Very customizable in my experience (working with it with .NET SwaggerGen tooling).

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.

Hey HN, Marc co-founder & CEO of scalar here!

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.

co-founder here :) Appreciate the kind words!

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

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.

appreciate your comment!

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 :)

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

appreciate your comment! So sorry to hear this, what iPhone do you have? I have an older iPhone so im not getting this issue.

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 :)

hey! We released a fix for Safari, it should be all fixed now. Let me know if this resolved it for you

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.

I like your project. Glad to see alternatives to this https://docusaurus-openapi.netlify.app/

Appreciate the comment :)

Sidenote: we are going to be building a docusaurus plugin soon!

Ooh this looks pretty sweet. Probably too new for me to convince my enterprise employer but will keep an eye on this for sure.

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 :)

Isn't swagger deprecated for like a decade? It looks like it supports OpenAPI, but interesting to focus on Swagger

https://en.wiktionary.org/wiki/genericization

We support Swagger + OAS 3/3.1

The language can be better throughout the repo so we will update that :) appreciate the comment

Yeah my perception of this is Swagger is old OpenAPI, so I would probably put OpenAPI front and center and just note that you also support Swagger?

Looks like a similar solution to https://github.com/stoplightio/elements - will give this a whirl some time!

Appreciate it! Don't hesitate to reach out (marc@scalar.com) if you have any feedback.

Cool to see this.

I hate redocly and swagger UI , and all of "enterprisey" offering on an open standard like OpenAPI.

co-founder here! thanks for the kind words.

I am also excited for another alternative, that feels modern!

How does this differ from stoplight.io?

Is it just another theme (not that we can’t use another theme)?

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.

Will /token oauth bearer authentication be added anytime soon?

yes! it's on our list of things to add this week, appreciate the comment :)

We just shipped adding headers + params interactive so people can add `x-api-key`

https://github.com/scalar/scalar/pull/237

Why did you decide to open-source it? How will you make money?

edit: why downvotes?

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.

hey ceo & co-founder here!

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 :)

The demo seems a little bit off-sync.

hey! co-founder here, what about the demo is off-sync?

We debounce the input slight before parsing the spec to not block the browser

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.

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.

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.

> 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

... or you can use Claude with it's 100,000 token limit. I've had some very impressive results from Claude against long documents.

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.

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.

You can DIY this with LangChain OpenAPI chain: https://python.langchain.com/docs/use_cases/apis

appreciate the comment!

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

Reply on news.ycombinator.com