OpenAPI / Swagger - Technological watch

Learn what is OpenAPI / Swagger in less than 5 minutes !
Wednesday, February 14, 2024


Before delving into Swagger, let’s address the underlying issue it aims to tackle: API complexity. As applications become more intricate, the number of APIs they rely on increases exponentially. Without proper documentation and management, this can lead to confusion, errors, and wasted time.

Traditionally, API documentation was a cumbersome process, often relegated to static documents that quickly became outdated. This lack of clarity made it challenging for developers to understand how to interact with APIs effectively. Additionally, inconsistencies in documentation could result in discrepancies between expectations and actual behavior, leading to frustration for both developers and end-users.

Swagger addresses these challenges by providing a unified platform for designing, documenting, and testing APIs. By standardizing the API documentation process and offering tools for automatic generation, Swagger streamlines development workflows and ensures consistency across projects. Developers can easily create interactive documentation that accurately reflects the API’s functionality, making it easier for team members to collaborate and integrate APIs into their applications.


  • OpenAPI refers to the specification itself.
  • Swagger refers to the toolkit enabling users to interact with this specification.

Initially known as Swagger, the specification underwent a transition when acquired by SmartBear, becoming part of the OpenAPI initiative and subsequently renamed OpenAPI. Despite this shift, the Swagger branding persists for products, both commercial and open-source, that facilitate working with the specification.


Here is a small example of a Swagger documentation.

openapi: 3.0.0
title: API example
description: A small description using **Markdown**
version: 1.0.0
- url:
description: A small server description
summary: Returns the list of posts
description: A description to explain
description: An array of posts
type: array
# // Define your schema here or provide a reference using $ref
# type: string
$ref: '#/components/schemas/Post'
type: object
type: integer
format: int64
example: 10
type: string
description: The title of the article
example: "Swagger - Technological watch"
type: string
description: The description of the article
example: "Learn what is Swagger in less than 5 minutes !"
type: array
type: string
- "Technological watch"
- "Feedback"
description: The tag list
example: ["Technological watch"]
type: string
format: date-time
type: boolean
example: false

You can find a very complete example here: Swagger editor.

Further Resources

Explore more about OpenAPI and Swagger through the following resources:

Additional Tools

Discover other useful tools for working with OpenAPI and Swagger:

  • Swagger Editor: A handy tool for creating and editing Swagger specifications.
  • Swagger UI: Visualize API routes and operations with ease using Swagger UI.

Example with swagger-php

If you’re working with PHP, you can utilize swagger-php to generate Swagger views directly from your codebase. Check out the swagger-php GitHub repository for more information.

Here’s a simple example showcasing how swagger-php can be used:

* @OA\Info(title="My First API", version="0.1")
* @OA\Get(
* path="/api/resource.json",
* @OA\Response(response="200", description="An example resource")
* )
public function index() {
return new Response(/* ... */);

This example illustrates how to use swagger-php to produce Swagger views tailored for your PHP-based APIs.

Recommended articles