What is OpenAPI Specs explain with example in Telugu And English

📖 What is the OpenAPI Specification?

The OpenAPI Specification (OAS)—formerly known as Swagger—is a universally accepted, standard format for describing RESTful APIs. It is a language-agnostic blueprint that allows both humans and computers to understand what an API does, how to use it, and what responses to expect, all without needing to look at the actual source code.

🍽️ Think of it like a restaurant menu for your code:

• 📋 The Menu: The OpenAPI Spec. It tells you what dishes (endpoints) are available.
• 🌶️ The Ingredients/Options: The parameters (e.g., “how spicy?”, “what ID?”).
• 🍲 The Meal: The JSON response you get back from the kitchen (the server).

✍️ Developers write OpenAPI specs in either YAML or JSON.

🚀 Why is OpenAPI Useful?

• 🖥️ Interactive Documentation: Tools like Swagger UI can read an OpenAPI spec and automatically generate a beautiful, interactive webpage where developers can test the API directly from their browser.
• ⚙️ Code Generation: You can feed an OpenAPI spec into tools that automatically write boilerplate server code or client SDKs in almost any programming language.
• 🤝 Standardization: It keeps frontend teams, backend teams, and external consumers on the exact same page regarding how the API functions.

💻 An Example of an OpenAPI Spec

Here is a simple example of an OpenAPI specification written in YAML. This spec describes a single API endpoint that retrieves a user’s profile based on their ID.

YAML

openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
  description: A simple API to retrieve user information.

servers:
  - url: https://api.example.com/v1

paths:
  /users/{userId}:
    get:
      summary: Retrieves a specific user by their ID.
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          description: The unique identifier of the user.
          schema:
            type: integer
            example: 42
      responses:
        '200':
          description: Successfully retrieved the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 42
        name:
          type: string
          example: Jane Doe
        email:
          type: string
          example: jane.doe@example.com

🔍 Breaking Down the Example

Here is exactly what the different sections of that file are doing:

• ℹ️ openapi & info: The metadata. It states the version of the OpenAPI standard being used (3.0.3), the name of your API, and its current version.
• 🌍 servers: The base URL where the API is hosted. All endpoint paths are appended to this URL.
• 🛣️ paths: The core of the spec. Here, we define an endpoint /users/{userId} and the HTTP method allowed (get).
• 🎛️ parameters: Explains the inputs required. In this case, we need a userId located in the URL path, and it must be an integer.
• 📨 responses: Defines what the API will return.
  • ✅ A 200 status means success, and it will return a JSON object shaped like a “User”.
  • ❌ A 404 status means the user doesn’t exist.
• 🧩 components: A reusable library of data structures. Instead of writing out what a “User” looks like every time we reference one, we define it once here (an object with an id, name, and email) and use $ref to point to it from the paths section.

📖 ఓపెన్ఎపిఐ (OpenAPI) స్పెసిఫికేషన్ అంటే ఏమిటి?

ఓపెన్ఎపిఐ స్పెసిఫికేషన్ (OAS) —దీనిని గతంలో స్వాగర్ (Swagger) అని పిలిచేవారు— ఇది RESTful APIలను వివరించడానికి ప్రపంచవ్యాప్తంగా ఆమోదించబడిన ఒక ప్రామాణిక ఫార్మాట్. ఇది ఏ ప్రోగ్రామింగ్ భాషకైనా (language-agnostic) సరిపోయే ఒక బ్లూప్రింట్ లాంటిది. అసలు సోర్స్ కోడ్‌ను చూడాల్సిన అవసరం లేకుండానే, ఒక API ఏమి చేస్తుందో, దాన్ని ఎలా ఉపయోగించాలో మరియు దాని నుంచి ఎలాంటి ప్రతిస్పందనలు (responses) ఆశించాలో మనుషులు మరియు కంప్యూటర్లు రెండూ అర్థం చేసుకునేలా ఇది చేస్తుంది.

🍽️ ఇది మీ కోడ్ కోసం ఒక రెస్టారెంట్ మెనూ లాంటిది అని అనుకోండి:

• 📋 మెనూ: ఓపెన్ఎపిఐ స్పెక్ (OpenAPI Spec). ఏయే వంటకాలు (endpoints) అందుబాటులో ఉన్నాయో ఇది మీకు చెబుతుంది.
• 🌶️ దినుసులు/ఎంపికలు: పారామితులు (parameters) (ఉదాహరణకు, “ఎంత కారంగా ఉండాలి?”, “ఏ ID కావాలి?”).
• 🍲 భోజనం: వంటగది (సర్వర్) నుండి మీకు లభించే JSON ప్రతిస్పందన (response).

✍️ డెవలపర్లు ఓపెన్ఎపిఐ స్పెక్స్‌ను YAML లేదా JSON ఫార్మాట్లలో రాస్తారు.

🚀 ఓపెన్ఎపిఐ ఎందుకు ఉపయోగపడుతుంది?

• 🖥️ ఇంటరాక్టివ్ డాక్యుమెంటేషన్: స్వాగర్ UI (Swagger UI) వంటి సాధనాలు ఓపెన్ఎపిఐ స్పెక్‌ను చదివి ఆటోమేటిక్‌గా ఒక అందమైన, ఇంటరాక్టివ్ వెబ్‌పేజీని సృష్టిస్తాయి. ఇక్కడ డెవలపర్లు తమ బ్రౌజర్ నుండే నేరుగా APIని పరీక్షించవచ్చు.
• ⚙️ కోడ్ జనరేషన్: మీరు ఓపెన్ఎపిఐ స్పెక్‌ను టూల్స్‌కి ఇస్తే, అవి దాదాపు ఏ ప్రోగ్రామింగ్ భాషలోనైనా బాయిలర్‌ప్లేట్ (boilerplate) సర్వర్ కోడ్‌ను లేదా క్లయింట్ SDKలను ఆటోమేటిక్‌గా రాస్తాయి.
• 🤝 ప్రామాణీకరణ (Standardization): API ఎలా పనిచేస్తుందనే విషయంపై ఫ్రంటెండ్ బృందాలు, బ్యాకెండ్ బృందాలు మరియు బయటి వినియోగదారులు (consumers) అందరూ ఒకే స్పష్టతతో ఉండేలా ఇది చేస్తుంది.

💻 ఓపెన్ఎపిఐ స్పెక్‌కి ఒక ఉదాహరణ

YAMLలో వ్రాసిన ఓపెన్ఎపిఐ స్పెసిఫికేషన్‌కు ఇది ఒక సాధారణ ఉదాహరణ. ఈ స్పెక్ ఒక యూజర్ యొక్క ID ఆధారంగా వారి ప్రొఫైల్‌ను తీసుకువచ్చే ఒకే ఒక API ఎండ్‌పాయింట్‌ను వివరిస్తుంది.

YAML

openapi: 3.0.3
info:
  title: User Management API
  version: 1.0.0
  description: A simple API to retrieve user information.

servers:
  - url: https://api.example.com/v1

paths:
  /users/{userId}:
    get:
      summary: Retrieves a specific user by their ID.
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          description: The unique identifier of the user.
          schema:
            type: integer
            example: 42
      responses:
        '200':
          description: Successfully retrieved the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 42
        name:
          type: string
          example: Jane Doe
        email:
          type: string
          example: jane.doe@example.com

🔍 ఉదాహరణను విశ్లేషిద్దాం (Breaking Down the Example)

ఆ ఫైల్‌లోని వివిధ విభాగాలు కచ్చితంగా ఏమి చేస్తున్నాయో ఇక్కడ వివరించబడింది:

• ℹ️ openapi & info: మెటాడేటా. ఇది ఉపయోగిస్తున్న ఓపెన్ఎపిఐ ప్రమాణం యొక్క వెర్షన్ (3.0.3), మీ API పేరు మరియు దాని ప్రస్తుత వెర్షన్‌ను తెలియజేస్తుంది.
• 🌍 servers: API హోస్ట్ చేయబడిన బేస్ URL. అన్ని ఎండ్‌పాయింట్ పాత్‌లు (paths) ఈ URLకి జోడించబడతాయి.
• 🛣️ paths: స్పెక్‌లో ఇది అత్యంత ముఖ్యమైన భాగం. ఇక్కడ, మనం /users/{userId} అనే ఎండ్‌పాయింట్‌ను మరియు అనుమతించబడిన HTTP పద్ధతిని (get) నిర్వచిస్తాము.
• 🎛️ parameters: అవసరమైన ఇన్‌పుట్‌లను వివరిస్తుంది. ఈ ఉదాహరణలో, మనకు URL పాత్‌లో ఉండే userId కావాలి, మరియు అది తప్పనిసరిగా ఒక ఇంటిజర్ (integer) అయి ఉండాలి.
• 📨 responses: API ఏమి తిరిగి ఇస్తుందో (return) ఇది నిర్వచిస్తుంది.
  • ✅ 200 స్టేటస్ (status) అంటే విజయం అని అర్థం, మరియు ఇది “యూజర్ (User)” ఆకారంలో ఉండే JSON ఆబ్జెక్ట్‌ను తిరిగి ఇస్తుంది.
  • ❌ 404 స్టేటస్ అంటే ఆ యూజర్ లేరు (కనుగొనబడలేదు) అని అర్థం.
• 🧩 components: ఇది డేటా స్ట్రక్చర్ల కోసం తిరిగి ఉపయోగించుకోగల (reusable) లైబ్రరీ. మనం “యూజర్”ను సూచించిన ప్రతిసారీ అది ఎలా ఉంటుందో రాయడానికి బదులుగా, మనం దానిని ఇక్కడ ఒకసారి నిర్వచిస్తాము (id, name, మరియు email ఉన్న ఆబ్జెక్ట్) మరియు paths విభాగం నుండి దానిని సూచించడానికి $ref ను ఉపయోగిస్తాము.