OpenAPI Specification (Swagger) in Rest API - Step-by-Step Execution

Concept Flow - OpenAPI Specification (Swagger)

Define API Info

↓

List Paths & Methods

↓

Describe Parameters

↓

Define Request & Response Schemas

↓

Add Security & Metadata

↓

Generate Documentation & Client Code

The OpenAPI Specification defines API details step-by-step, from info to paths, parameters, schemas, and security, ending with documentation generation.

Execution Sample

Rest API

openapi: 3.0.0
info:
  title: Simple API
  version: 1.0.0
paths:
  /hello:
    get:
      responses:
        '200':
          description: Success

This YAML snippet defines a simple API with one GET endpoint /hello returning a 200 success response.

Execution Table

Step	Section Processed	Action	Result
1	openapi	Read version '3.0.0'	Set spec version to 3.0.0
2	info	Read title and version	API named 'Simple API' version '1.0.0'
3	paths	Read path '/hello'	Register endpoint '/hello'
4	paths -> get	Read GET method	Define GET operation for '/hello'
5	responses	Read response code '200'	Set response description 'Success'
6	End	No more sections	Specification ready for use

💡 All sections processed, OpenAPI spec fully defined

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	Final
spec_version	undefined	3.0.0	3.0.0	3.0.0	3.0.0	3.0.0	3.0.0
api_info	empty	empty	{title: 'Simple API', version: '1.0.0'}	{title: 'Simple API', version: '1.0.0'}	{title: 'Simple API', version: '1.0.0'}	{title: 'Simple API', version: '1.0.0'}	{title: 'Simple API', version: '1.0.0'}
paths	empty	empty	empty	{'/hello': {}}	{'/hello': {get: {}}}	{'/hello': {get: {responses: {'200': {description: 'Success'}}}}}	{'/hello': {get: {responses: {'200': {description: 'Success'}}}}}

Key Moments - 3 Insights

Why do we specify 'openapi: 3.0.0' at the start?

This tells tools which OpenAPI version to use. See execution_table step 1 where spec_version is set to '3.0.0'. Without it, tools might not understand the spec.

What happens if we forget to define responses for a path?

Responses describe what the API returns. In execution_table step 5, response '200' is set. Without responses, the API is incomplete and tools may warn or fail.

How does OpenAPI handle multiple HTTP methods on the same path?

Each method (get, post, etc.) is a separate key under a path. In step 4, 'get' is defined. You can add 'post', 'put', etc. similarly under the same path.

Visual Quiz - 3 Questions

Look at the execution_table, what is the API title after step 2?

A 'Simple API'

B 'My API'

C undefined

D 'API Version 1'

💡 Hint

Check the 'api_info' variable in variable_tracker after step 2

At which step is the GET method for '/hello' defined?

A Step 3

B Step 4

C Step 5

D Step 2

💡 Hint

See execution_table row where 'paths -> get' is processed

If we add a POST method to '/hello', which variable in variable_tracker changes?

A spec_version

B api_info

C paths

D responses

💡 Hint

Adding methods changes the 'paths' structure as shown in variable_tracker

Concept Snapshot

OpenAPI Specification (Swagger) defines REST APIs in a structured YAML/JSON format.
Start with 'openapi' version, add 'info' for API metadata.
Define 'paths' with HTTP methods and their parameters.
Specify 'responses' to describe outputs.
Use this spec to generate docs and client code.

Full Transcript

OpenAPI Specification (Swagger) is a way to describe REST APIs clearly. It starts by specifying the version with 'openapi: 3.0.0'. Then, the 'info' section gives the API a name and version. Next, 'paths' list the API endpoints like '/hello'. Under each path, HTTP methods like GET are defined. Each method includes 'responses' that explain what the API returns, such as a 200 success message. This structured format helps tools create documentation and client code automatically. The execution table shows how each part is read and stored step-by-step, and the variable tracker follows how the API details build up. Common confusions include why the version is needed, the importance of responses, and how multiple methods are handled on one path. Quizzes test understanding of these steps and variables. Overall, OpenAPI makes APIs easy to understand and use.

Practice

1. What is the main purpose of the OpenAPI Specification in REST APIs?

easy

A. To store user data securely

B. To execute API requests automatically

C. To replace the need for API servers

D. To describe the API endpoints, methods, and data formats in a standard way

Solution

1. Step 1: Understand OpenAPI's role

   OpenAPI Specification is designed to describe APIs clearly and consistently.

2. Step 2: Identify the correct purpose

   It documents endpoints, HTTP methods, parameters, and data formats for APIs.

3. Final Answer:

   To describe the API endpoints, methods, and data formats in a standard way -> Option D

4. Quick Check:

   OpenAPI = API description standard [OK]

Hint: OpenAPI is for describing APIs, not running or storing data [OK]

Common Mistakes:

• Confusing OpenAPI with API execution tools
• Thinking OpenAPI stores user data
• Believing OpenAPI replaces servers

2. Which of the following is the correct way to define an HTTP GET method for the path /users in OpenAPI YAML?

easy

A. paths:
get:
/users:
summary: Get all users

B. paths:
/users:
get:
summary: Get all users

C. get:
paths:
/users:
summary: Get all users

D. paths:
/users:
post:
summary: Get all users

Solution

1. Step 1: Check OpenAPI path structure

   Paths are keys under paths, then HTTP methods like get are nested under each path.

2. Step 2: Validate correct nesting and method

   paths: /users: get: summary: Get all users correctly places /users under paths and get under /users.

3. Final Answer:

   paths: /users: get: summary: Get all users -> Option B

4. Quick Check:

   Paths > /users > get [OK]

Hint: Remember: paths > endpoint > method > details [OK]

Common Mistakes:

• Swapping method and path levels
• Using wrong HTTP method for GET
• Incorrect YAML indentation

3. Given this OpenAPI snippet, what is the response code defined for a successful GET request to /items?

paths:
  /items:
    get:
      responses:
        '200':
          description: Successful response
        '404':
          description: Not found

medium

A. 200

B. 201

C. 500

D. 404

Solution

1. Step 1: Locate response codes under GET method

   The snippet shows responses under get for /items.

2. Step 2: Identify success response code

   Code 200 is labeled as "Successful response", indicating success.

3. Final Answer:

   200 -> Option A

4. Quick Check:

   Success = 200 HTTP code [OK]

Hint: Success responses usually use 200 code [OK]

Common Mistakes:

• Choosing 404 as success code
• Confusing 201 (created) with 200
• Ignoring response codes listed

4. Identify the error in this OpenAPI YAML snippet:

paths:
  /login:
    post:
      summary: User login
      responses:
        200:
          description: Login successful

medium

A. Summary field is not allowed under POST

B. Missing requestBody for POST method

C. Response code 200 should be a string '200', not a number

D. Path should start with a capital letter

Solution

1. Step 1: Check response code format

   OpenAPI requires response codes as strings, e.g., '200', not numbers.

2. Step 2: Verify other fields

   Summary is allowed; requestBody is optional; path case is flexible.

3. Final Answer:

   Response code 200 should be a string '200', not a number -> Option C

4. Quick Check:

   Response codes must be strings [OK]

Hint: Always quote response codes as strings in YAML [OK]

Common Mistakes:

• Using numeric response codes
• Assuming requestBody is mandatory
• Thinking summary is invalid

5. You want to document an API that returns a list of products with optional filtering by category. Which OpenAPI feature helps you define the optional category filter parameter for the GET /products endpoint?

hard

A. Use a query parameter with required: false under the GET method

B. Add a path parameter named category in the URL

C. Include category in the requestBody schema

D. Define category as a header parameter

Solution

1. Step 1: Understand parameter types

   Optional filters are usually query parameters, not path or header parameters.

2. Step 2: Define optional query parameter

   Set required: false for the category query parameter under GET.

3. Final Answer:

   Use a query parameter with required: false under the GET method -> Option A

4. Quick Check:

   Optional filters = query params with required false [OK]

Hint: Filters usually go as optional query parameters [OK]

Common Mistakes:

• Using path parameters for optional filters
• Putting filters in requestBody for GET
• Defining filters as headers