OpenAPI / Swagger - Technological watch

Problematic

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.

Definitions

• 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.

Examples

Here is a small example of a Swagger documentation.

openapi: 3.0.0
info:
  title: API example
  description: A small description using **Markdown**
  version: 1.0.0
servers:
  - url: https://api.alexandre-hublau.com/v1
    description: A small server description
paths:
  /posts:
    get:
      summary: Returns the list of posts
      description: A description to explain
      responses:
        '200':
          description: An array of posts
          content:
            application/json:
              schema:
                type: array
                items:
                    # // Define your schema here or provide a reference using $ref
                    # type: string
                    $ref: '#/components/schemas/Post'

components:
  schemas:
    Post:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        title:
          type: string
          description: The title of the article
          example: "Swagger - Technological watch"
        description:
          type: string
          description: The description of the article
          example: "Learn what is Swagger in less than 5 minutes !"
        tags:
          type: array
          items:
            type: string
            enum:
              - "Technological watch"
              - "Feedback"
          description: The tag list
          example: ["Technological watch"]
        date:
          type: string
          format: date-time
        draft:
          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:

• OpenAPI and Swagger Documentation: Detailed documentation covering various aspects of OpenAPI and Swagger.

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.