ndimares

We literally just did something like this on Gram, not exactly what you're saying, but it's pretty close... https://www.speakeasy.com/blog/how-we-reduced-token-usage-by...

We have a platform (Gram) which is serverless MCP. Now users can launch MCP servers that only have 3 tools, search, describe, execute. Gram handles the tool routing, and execution (acting sort of like the sandbox). So the client only ever needs to know about those three tools. Everything else is abstracted.

If you want a lightweight API docs replacement, I'd recommend Scalar. Simple and easy to use, but so much better than Swagger docs...

I'd like to say this was a clever ruse so that real people could reach me and bots wouldn't, but that'd be a lie. I just fat fingered it.

Caveat that I work for Speakeasy, but there are a few tools you can look at:

- Speakeasy

- Fern

- Stainless

First SDK with Speakeasy is free and we also have discounts for companies who are just starting out.

Feel free to shoot me an email if we can be useful: nolan@spakeasy.com :)

Hi, I work at Speakeasy. Thanks for this. I'll look into this and correct the post. Thanks :)

Code-first or spec first, doesn't matter. Everything you need to figure out how to write an OpenAPI spec.

Anotha one

There's a lot of new companies that have started to address this issue. One of which I work at: https://www.speakeasy.com/

I genuinely think that the quality is beyond what exists in the GraphQl ecosystem.

I'm so excited to get 1.0 integrated on the site!

Hi all! we wrote this post a couple weeks ago. The TL;DR is that we recently built an API Key authorization flow that can integrate into any API provider's Gateway and makes it trivially easy for them to provide their users self-service API key management: https://speakeasyapi.dev/docs/product-reference/speakeasy-pl...

To get that working we first evaluated every commonly-used auth method before deciding on a fairly unique approach, Signed Tokens as API Keys, but with 1 Signing Key Per API key.

Happy to answer any questions people have about this novel approach, or anything API auth related. If anyone wants to try out the tool here's the sign up for the waitlist: https://speakeasyapi.dev/request-access/

Threw together a Python SDK: https://github.com/speakeasy-sdks/rows-python-sdk :) Hope it helps, and let me know what you think!

Looks nice, can you autogenerate the reference from an OpenAPI spec ?

Depending on the nature of the API, you could wrap it in a react component (if that's likely what users would do), and then embed it onto your landing page so that people could interact with it.

I knew I was a distractible person, but I never realised the degree to which having the URL and tabs at the top of my browser was a drag on my productivity until I began using Arc. Now, I basically always keep Arc in focus mode and it has had a really positive impact on my concentration. There are definitely things about the browser that bother me, but this one benefit has been enough to make it my new default.

This is very cool, it's good to see people working to build bridges that make it easy to interface with blockchain data. Do you guys have an openAPI spec for the API?

Awesome, if you want any help with the OpenAPI spec, find us in slack and we can answer questions: https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1cwb... (we know quite a bit about OpenAPI).

If you have an OpenAPI spec, we're building an SDK generator that improves upon some of the standard openAPI SDK tools. You can check it out here: https://docs.speakeasyapi.dev/docs/using-speakeasy/client-sd...

The SDKs are language-idiomatic, fully typed and easily human readable. We got support for: Go, Python, and TS. Hope it helps!

Hi I'm actually working on a guide for this exact topic. My basic thoughts are that there's currently no magic bullet solution and it depends primarily on your technical ability and resourcing:

-0 technical skills: notion or atlassian -pseudotechnical (github & markdown skill): gitbook, or readme -technical with resourcing constraints: docusaurus, or hugo or mkDocs. -technical w/o constraints: custom react site: Markdoc + Next.js or Gatsby

The company I'm at is currently technical w/ constraints. We use docusaurus and we use a plugin for autogenerating the openapi documentation: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs

It works. The results are not spectacular, merely passable. We think in the near future we will build our own plugin for the community. If you ever want to char docs, get in touch!

Wha's always boggled me about Postman is that it doesn't have autosave. It's 2022, what doesn't have autosaving? So thank you for adding auto-saving, huge improvement on Postman!

Congratulations on the release! What're your long term plans for the tool? What are you planning on building next?

There is a lot of activity in the space of SDK generators. If you have an OpenAPI schema, you should be able to find tooling that can get you 80% of the way there. Here's a small app our team put together a couple weeks ago that you might like: https://easysdk.xyz/

We've expanded support for Python and Go since we made this. If you're interested in testing out the multi-language version, let me know!

Some other solutions: -OpenAPI: http://github.com/openapitools/openapi-generator -(language specific) Go SDK: https://github.com/deepmap/oapi-codegen

Best of luck with finding a solution that works for your use case!

We built something like this. SDK you can drop into your API code, then we generate an OpenAPI spec based off of your traffic. Demo here: https://www.loom.com/share/c5b242d25de84e1d95b03fd35eab7099

I really like https://getstream.io/ docs. For me, SDK support is important, as are examples and templates that I can play with & build off of. I also like the API usage dashboard that Stream supplies when you login. Which veers into the terriory of dev portal, but worth mentioning.

Also, in terms of tools for actually building documentation, I recommend looking at https://docusaurus.io/ for clean, customisable documentation.

Thanks! Spot on. For embedding in the site, we used a lottie animation with the lottie-web NPM library. As for the lottie animation, I worked with a contractor on fiverr (this is him: https://www.fiverr.com/meerazzum?source=order_page_summary_s...). Would absolutely recommend him. I gave him a sloppy figma mockup and he brought it to life.

Let me know if you have more questions.

No firm ETA right now, but it's something we're currently working on :)

Will send you a private message when it's ready.

We're working on expanding the generator to be able to easily add new languages. Will definitely look at supporting C#!

I've never used any of the products, but there are some interesting developments in the "code visualisation" space, i.e. https://www.codesee.io/. My sense is that right now they're mainly targeting use case #1 that you mentioned, but I'm interested in whether they will grow to be useful for use case #3 which you mentioned.

The project I work on (speakeasyapi.dev) is more focused on the public API side for now, but we've looked at the microservice problem. We've come at it from the angle of providing an SDK which can track the traffic to a service. That way you can be aware of your services true surface area vs. what's documented.

Curious to hear other ways people are solving these problems.

Hey very cool blog post. Have you guys looked at adding client SDKs for your API? Also wondering if the go-swagger generated openAPI specs have any gaps or if it is sufficiently complete in your eyes.

I think it depends on your end users. If you're building a product for devs, personally, I think it's worth investing in a great docs experience and more 'advanced' features. Docs are going to be one of your most used interfaces. But you should make sure that making docs 'pretty' isn't detracting from usability. If you're making internal docs, then ya, I agree with you, keep it dead simple.

This is pretty fascinating. Feels like within the ‘X as code’ movement, there is a schism between SQL and functional languages. The folks who have learned programming via the data analysts and BI spaces seem to be building a fully fledged SQL stack.