Scalar: Generate interactive API documentations from Swagger files

#1

Post by agmiklas » Fri, Oct 13, 2023, 3:15 PM UTC

Scalar: Generate interactive API documentations from Swagger files
github.com

Re: Scalar: Generate interactive API documentations from Swagger files

#2

Post by chrisweekly » Fri, Oct 13, 2023, 4:33 PM UTC

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

Re: Scalar: Generate interactive API documentations from Swagger files

#3

Post by cameronrohani » Fri, Oct 13, 2023, 4:38 PM UTC

chrisweekly wrote: post #2

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

Re: Scalar: Generate interactive API documentations from Swagger files

#4

Post by maxloh » Fri, Oct 13, 2023, 4:39 PM UTC

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

Re: Scalar: Generate interactive API documentations from Swagger files

#5

Post by ushakov » Fri, Oct 13, 2023, 4:42 PM UTC

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

edit: why downvotes?

Re: Scalar: Generate interactive API documentations from Swagger files

#6

Post by cameronrohani » Fri, Oct 13, 2023, 4:52 PM UTC

ushakov wrote: post #5

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#7

Post by cameronrohani » Fri, Oct 13, 2023, 4:52 PM UTC

maxloh wrote: post #4

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#8

Post by simonw » Fri, Oct 13, 2023, 4:53 PM UTC

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#9

Post by cameronrohani » Fri, Oct 13, 2023, 5:02 PM UTC

simonw wrote: post #8

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#10

Post by melolife » Fri, Oct 13, 2023, 5:03 PM UTC

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