6 posts tagged with "swagger"

Using $ref to reference a reusable parameter in an OpenAPI specification is a key practice for keeping your API definitions clean, consistent, and maintainable. This method centralizes common parameters, like Authorization headers or a userId path parameter, in a single location and allows you to reference them from any endpoint.

Creating a mock server from a Swagger/OpenAPI file is a powerful way to decouple front-end and back-end development. It allows front-end developers to start building and testing their applications against a realistic API without waiting for the back-end to be completed.

Here's a step-by-step guide on how to set up a simple mock server using your OpenAPI specification file.

In OpenAPI, the correct way to declare a date is by using the string type along with a specific format. The format distinguishes a date from a regular string and provides a standard for validation and code generation.

Using 'Authorization: Bearer <token>' in an OpenAPI (Swagger) specification requires defining a security scheme and then applying it to the relevant API endpoints. The method for doing this varies slightly between OpenAPI versions 2.0, 3.0, and 3.1.

The meaning of required in OpenAPI (or Swagger) is consistent across all major versions: it specifies that a property must be present in the data payload. However, how you use and apply the keyword has evolved between versions.

When defining server URLs in OpenAPI specs, you often need to reference environment-specific values (like staging or production subdomains). But using raw environment variables can result in placeholder values like default: unknown, which may confuse tools like Swagger UI, ReDoc, or code generators.

This guide explains the issue and offers clean solutions - with practical examples.