swagger-petstore VS openapi-directory

Now, we can start our server and visit the Swagger UI at http://localhost:port/documentation. The documentation will be empty for now, but we will add our endpoints later on. You can also have a look at how the Swagger UI looks in the Swagger's online demo.

I think there's also a missing gap in how to present Swagger beautifully, the default one ( https://petstore.swagger.io/ ) is meh. I'm looking for something that can generate like https://stripe.com/docs/api but open source (since the OP is talking about it).

I imagine a tool(chain) that can take Swagger generated from annotations in code, and combine it with a folder containing Markdown files for "free form" documentation, and generate a Hugo/Jekyll static site that can be deployed in Cloudflare Pages in docs.mycompany.com

You can go to https://petstore.swagger.io/

Controllers handle the incoming requests, and their responses. Generally you design a "contract" that describes how to properly format a request to your application, and which response you may expect. Swagger is the tool to write the contract, and REST are the principles that guide you. Take a look at the swagger petstore for an example. Ask for a swagger file of your application, and the corresponding Controller, and you should be able to see the connection.

Your question is a bit unclear. Are you trying to find an example OpenAPI document for some REST web services? If yes, check the Pet Store project: https://petstore.swagger.io/

So you mean there is an endpoint on each of your service that will bring you to a view like the PetStore example?

I am a backend dev myself. I use pet store api collection as a reference for REST APIs best practices https://petstore.swagger.io

Automation for many routines starts with interaction via API. This case can be treated in many ways, but I want to take a look at interacting with web API using a generated Kotlin client. I found a lot of academic examples for generating Kotlin clients (most of them are based on the PetStore), but nothing was close to real-world examples. My goal is to build a Kotlin client for a complex API and see how it works. Here is the source code of the Kotlin project that I will use in the post.

Use APIs.gurufor exploring well-documented OpenAPI files. For example, imagine you are interested in integrating a weather API. By searching for "weather" on APIs.guru, you find several options.

Furthermore, since we can split the generated code into multiple parts based on tag filtering, we can also create different SDKs from different resources or even publicly available APIs. There is an extensive list of publicly available OpenAPI specifications on SwaggerHub, RapidAPI and APIs.guru.

Maybe you'd like to integrate with APIs.guru?

https://apis.guru

In this specific case, I'm auto-publishing (now fully automatically, once a month) a package that wraps content from elsewhere bundling it with some utilities to make that useful in JS and available via NPM. For cases like this it's useful to have a patch update once a month that just updates the upstream content & republishes.

- Crawl API repositories like apis.guru

This should go without saying, but the types inside your API specification should be specific in order to be useful. The main way I see this appear is that some specification generators seem to default to "string" for everything, even if something else makes sense. In an analysis of 1154 specifications from OpenAPI directory, I found that 60% of the field types were strings. Many of these were instances that made sense, such as IDs or names, but many were misused types: for example, there was a year value encoded with type "string," and a boolean value with type "string" and enum "true" or "false". Using too-broad types such as strings can make it harder to understand the specification, and decrease the effectiveness of certain tools.

I haven’t used it but have skimmed through it, but https://apis.guru has collected information on lots of APIs. You might find something interesting.

Try the integration designer with your OpenAPI documents. If you don’t have any document handy, we prepared a few examples for you, or you can find more OpenAPI documents on APIs.guru.

apis.guru is a nice site with APIs listed for many orgs.