Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Scalar: Generate interactive API documentations from Swagger files

github.com

Post reply on HN
Print view View original

11–20 of 74 posts

Re: Scalar: Generate interactive API documentations from Swagger files

#11

Post by cameronrohani »

melolife wrote: post #10

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 m…

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#12

Post by majkinetor »

maxloh wrote: post #4

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

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#13

Post by desiderantes »

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#14

Post by simonw »

cameronrohani wrote: post #9
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.

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#16

Post by majkinetor »

cameronrohani wrote: post #9
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.

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#17

Post by CharlieDigital »

majkinetor wrote: post #12
maxloh wrote: post #4

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

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

Re: Scalar: Generate interactive API documentations from Swagger files

#19

Post by einpoklum »

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.

Post reply on HN