guide: how to create openapi spec

[muhfaris]

Guide for Creating OpenAPI Specifications

This guide outlines the rules and best practices for creating OpenAPI specifications. By following these guidelines, you can ensure a consistent and well-documented API.

---

General Rules

1. Operation ID:

   • Every path endpoint in the OpenAPI specification must have an operationId.
   • The operationId should follow one of these formats:
     • <HandlerName>
     • <HandlerName::ServiceName>

2. Tags:

   • Every path endpoint must have one or more tags.
   • Tags should be used to categorize endpoints logically (e.g., by resource, functionality, or service).

---

Steps to Create an OpenAPI Specification

1. Define the Basics

Start with the fundamental structure of the OpenAPI document:

openapi: 3.0.0
info:
  title: Your API Title
  description: A brief description of your API.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1

2. Add Paths and Endpoints

For each API endpoint, include the following:

• Path: Specify the endpoint (e.g., /users, /orders/{id}).
• HTTP Methods: Define the HTTP method (GET, POST, PUT, DELETE, etc.).
• Operation ID: Assign a unique and meaningful operationId for the method.
• Tags: Associate relevant tags for better organization.

Example:

paths:
  /users:
    get:
      summary: Retrieve a list of users
      operationId: GetUsers
      tags:
        - Users
      responses:
        '200':
          description: A list of users

  /orders/{id}:
    delete:
      summary: Delete an order by ID
      operationId: DeleteOrder::OrderService
      tags:
        - Orders
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the order to delete
          schema:
            type: string
      responses:
        '204':
          description: Order successfully deleted

3. Add Components (Optional)

If applicable, define reusable components such as schemas, parameters, and responses:

Example:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
  responses:
    NotFound:
      description: Resource not found

---

Full OpenAPI Specification Example

Here is a complete example of an OpenAPI specification based on the description:

openapi: 3.0.0
info:
  title: Example API
  description: An example API to demonstrate the OpenAPI specification.
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: Retrieve a list of users
      operationId: GetUsers
      tags:
        - Users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /orders/{id}:
    delete:
      summary: Delete an order by ID
      operationId: DeleteOrder::OrderService
      tags:
        - Orders
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the order to delete
          schema:
            type: string
      responses:
        '204':
          description: Order successfully deleted
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
  responses:
    NotFound:
      description: Resource not found

---

Best Practices

• Use Meaningful operationId Values:

  • Avoid generic names like GetData or FetchInfo.
  • Instead, use descriptive names that reflect the purpose of the handler.

• Organize with Tags:

  • Group endpoints by logical functionality.
  • For example, use tags like Users, Orders, Authentication, etc.

• Consistency:

  • Maintain consistent naming conventions across all paths and components.
  • Use the same tag format throughout the document.

---

By adhering to these rules and recommendations, your OpenAPI specification will be easier to understand, maintain, and utilize by developers and consumers alike.