swagger-editor VS mermaid

To test it out, you can copy the generated build file and paste it in Swagger live editor.

One of the powerful features of OpenAPI is the ability to generate code automatically. Using tools like Swagger, you can generate both client and server code using options "Generate Server" or "Generate Client" available on https://editor.swagger.io/

Install Swagger tools like Swagger Editor, Swagger UI, and Swagger Codegen.

Having docs as the JSON file is the most important, but can we also present it somehow? Sure we can. Enter Swagger UI! And I am not talking about the Swagger Editor, but our very own instance!

I did the same for the other API and adjusted the spec using the Swagger Editor. Specifically, I added detailed descriptions that should help the agent understand the API usages. The resulting OpenAPI YAML file is as follows:

It has an online editor. You can easily play around with it and generate easy-to-use documentation.

After running the collection, I can see the API spec that was created and the mock server endpoint to test it. Looking at the rendered version on Swagger's OAS editor we can see pretty clearly this is a complete API that gets us exactly what we need.

While there’s not an officially supported Java SDK for Marqeta, building a Java client is quite straightforward, as the Core API is documented in both Swagger v2.0 and OpenAPI v3.0. The OpenAPI documentation is in beta, but it is generated directly from the API source code. To get a Java client, all we need to do is drop the OpenAPI yaml file into editor.swagger.io, modify the servers section to use the https://sandbox-api.marqeta.com/v3 as the URL, and tell it to generate a Java client.

Check out https://editor.swagger.io/ as a start point. In theory you should be able to generate a client for any swagger complient api and plug in your own auth and custom logic.

I would suggest using the swagger editor: https://editor.swagger.io/

* Drawn by mermaid.

The Markdown format is a blessing for documentation. While many are aware it can create headings, tables, text styles, and lists, not many know about extensions available to the basic Markup language. Today, we'll learn about Mermaid.js. This powerful yet simple diagramming tool speaks to the aspirations of Markdown format.

The diagrams in the first half of the article are made with tldraw https://www.tldraw.com/

The lower half look like the output from Mermaid https://mermaid.js.org/

Lets, assume we want to add rendered Mermaid diagrams to our page by transforming the source code in fenced code blocks like the following:

I might know nothing about debates, but in my impression you always make the diagram that does its job best. Argdown seems to constrain everything to its framework and forces the style of the output.

Also, Mermaid (https://mermaid.js.org/) exists.

i hope they'll eventually support Mermaid (https://github.com/mermaid-js/mermaid) for creating diagrams directly within documents. i've been using it a lot for my markdown files and it works amazingly well with LLMs (e.g. asking LLM to generate the diagram representation of something using Mermaidjs)