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

51–60 of 74 posts

Re: Scalar: Generate interactive API documentations from Swagger files

#51

Post by Jka9rhnDJos »

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

Re: Scalar: Generate interactive API documentations from Swagger files

#52

Post by oooyay »

marclave wrote: post #50

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.

Re: Scalar: Generate interactive API documentations from Swagger files

#53

Post by marclave »

Jka9rhnDJos wrote: post #51

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…

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

Re: Scalar: Generate interactive API documentations from Swagger files

#54

Post by einpoklum »

einpoklum wrote: post #19

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.

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

Re: Scalar: Generate interactive API documentations from Swagger files

#56

Post by marclave »

oooyay wrote: post #52
marclave wrote: post #50

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

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

Re: Scalar: Generate interactive API documentations from Swagger files

#57

Post by hahnbee »

bamazizi wrote: post #30

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

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!

Post reply on HN