APIMatic Validation Report

Validation Summary

Introduction

This API definition validation report for aliraza1231 was compiled on January 28, 2025. It provides a summary of the validation results for all involved API definitions.

What is APIMatic?

APIMatic is a Developer Experience platform for Web APIs, offering auto-generated SDKs, usage examples, and interactive documentation. Our goal is to streamline API onboarding and adoption.

API Definition Validation

APIMatic ensures API specifications are syntactically and semantically correct to generate high-quality documentation and SDKs. This report details the validation results, highlighting any blockers that must be resolved. Visit our official documentation for more information.

Fixing Validation Issues

To resolve issues or re-validate API definitions, use our VS Code extension Fix My OpenAPI, which offers dedicated views and other features for improving API definitions.

Contact Us

For queries or concerns, reach out to us at support@apimatic.io .

Data Overview

This report analyzes an API named Simple API overview. which is defined using the specification format OpenAPI v3.0 (JSON). The files involved are listed below:

#	File Path	File Specification Format
1	api-with-examples.json	OpenAPI v3.0 (JSON) (Main File)

Table of Contents

• Validation Summary
• Data Overview
• Validation Issues (0)
• Lint Issues (7)
  • Error Issue No. 1 - No API server found. (1)
  • Error Issue No. 2 - Required schema is missing from the media type object. (4)
  • Warn Issue No. 3 - Contact information is missing. (1)
  • Warn Issue No. 4 - Operation object's tags are empty or missing. (2)
  • Info Issue No. 5 - The root OpenAPI file name does not follow recommended conventions. (1)
  • Info Issue No. 6 - Info object description is missing. (1)
  • Info Issue No. 7 - Example object summary and description are missing. (4)

Validation Issues

No validation issues were found.

Lint Issues

A total no. of 7 lint issues were found which are listed below:

• Error Issue No. 1 - No API server found. (1)
• Error Issue No. 2 - Required schema is missing from the media type object. (4)
• Warn Issue No. 3 - Contact information is missing. (1)
• Warn Issue No. 4 - Operation object's tags are empty or missing. (2)
• Info Issue No. 5 - The root OpenAPI file name does not follow recommended conventions. (1)
• Info Issue No. 6 - Info object description is missing. (1)
• Info Issue No. 7 - Example object summary and description are missing. (4)

Error Issue No. 1 - No API server found. (1)

Rule Id	required-servers
Ruleset Id	openapi-v3-codegen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Servers
Possible Impact On Output Of	Code Generation , Developer Experience Portal

Description

OpenAPI root object must specify at least one server using the `servers` property. Information about the servers provide connectivity information related to a target server of the API. Empty servers defaults to localhost which can prevent your end-users from consuming your API.

Tips

• Ensure that the servers list has been defined in the root OpenAPI object.
• Ensure that the servers list contains at least one Server Object definition.
• Ensure that the Server Object contains all required properties.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#oasObject
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: api-with-examples.json , Line No: 1, Line Pos: 1 - Line No: 1, Line Pos: 2, Path: #

Error Issue No. 2 - Required schema is missing from the media type object. (4)

Rule Id	required-media-type-schema
Ruleset Id	openapi-v3-apimatic-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Media Types
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

Each media type object must have an associated schema defined. The schema defines the structure and data format for the content of the media type.

Tips

• Ensure that a schema is defined within the media type object.
• Make sure the schema is properly formatted and matches the expected data structure and format for the media type.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#media-type-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (4)

1. File: api-with-examples.json , Line No: 16, Line Pos: 35 - Line No: 16, Line Pos: 36, Path: # > paths > / > get > responses > 200 > content > application/json
2. File: api-with-examples.json , Line No: 53, Line Pos: 35 - Line No: 53, Line Pos: 36, Path: # > paths > / > get > responses > 300 > content > application/json
3. File: api-with-examples.json , Line No: 73, Line Pos: 35 - Line No: 73, Line Pos: 36, Path: # > paths > /v2 > get > responses > 200 > content > application/json
4. File: api-with-examples.json , Line No: 122, Line Pos: 35 - Line No: 122, Line Pos: 36, Path: # > paths > /v2 > get > responses > 203 > content > application/json

Warn Issue No. 3 - Contact information is missing. (1)

Rule Id	required-info-contact
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Info
Possible Impact On Output Of	Developer Experience Portal

Description

The Info Object must specify contact information using the `contact` property. This information helps users who may be stuck using your API e.g. you can include contact details of your support team that your API consumers can reach out to.

Tips

• Ensure that the Info Object contains the `contact` property.
• Ensure that the contact details are complete and not empty or null e.g. remember to add the name, url and email.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#info-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#contactObject
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: api-with-examples.json , Line No: 3, Line Pos: 11 - Line No: 3, Line Pos: 12, Path: # > info

Warn Issue No. 4 - Operation object's tags are empty or missing. (2)

Rule Id	at-least-one-operation-tag
Ruleset Id	openapi-v3-apimatic-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Operations
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

The Operation Object must specify one or more tags using the `tags` property. Tags are used for logical grouping of operations. This facilitates their discovery and consequently eases API consumption.

Tips

• Ensure that the tag list is present in the Operation Object using the `tags` property.
• Ensure that the tag list is not empty.
• Ensure that the tag list contains at least one tag entry.
• The tag can represent the resource the operations belong to or a user-friendly category that can help group those operations together.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (2)

1. File: api-with-examples.json , Line No: 9, Line Pos: 14 - Line No: 9, Line Pos: 15, Path: # > paths > / > get
2. File: api-with-examples.json , Line No: 66, Line Pos: 14 - Line No: 66, Line Pos: 15, Path: # > paths > /v2 > get

Info Issue No. 5 - The root OpenAPI file name does not follow recommended conventions. (1)

Rule Id	valid-openapi-file-naming-conventions
Ruleset Id	openapi-v3-standards-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Root Information
Possible Impact On Output Of	API Transformer , Code Generation, Developer Experience Portal

Description

The root OpenAPI document is recommended to be named as either `openapi.json` or `openapi.yaml` depending upon the data format used in the file.

Tips

• Main or root OpenAPI file is one which contains the OpenAPI version, paths and other information.
• Standardized naming of files helps improve their discoverability for your users.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#document-structure
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#document-structure
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: api-with-examples.json , Line No: 1, Line Pos: 1 - Line No: 1, Line Pos: 2, Path: #
   • Current File Name: api-with-examples.json

Info Issue No. 6 - Info object description is missing. (1)

Rule Id	info-description-exists
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Info
Possible Impact On Output Of	Developer Experience Portal

Description

The Info Object must specify details about the API using the `description` property. The value of the description must be non-null and non-empty.

Tips

• Ensure that the Info Object contains the `description` property.
• Ensure that Info Object description value is not null or empty.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#info-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (1)

1. File: api-with-examples.json , Line No: 3, Line Pos: 11 - Line No: 3, Line Pos: 12, Path: # > info

Info Issue No. 7 - Example object summary and description are missing. (4)

Rule Id	example-summary-or-description-exists
Ruleset Id	openapi-v3-docsgen-linting
Type of Issue	Semantic
Broad Category of Issue	OpenAPI Examples
Possible Impact On Output Of	Developer Experience Portal

Description

Example Object must have a non-null and non-empty description or summary.

Tips

• Add a user-friendly description for the example object.

For More Information

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#example-object
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md

Affected Components (4)

1. File: api-with-examples.json , Line No: 18, Line Pos: 26 - Line No: 18, Line Pos: 27, Path: # > paths > / > get > responses > 200 > content > application/json > examples > foo
2. File: api-with-examples.json , Line No: 55, Line Pos: 26 - Line No: 55, Line Pos: 27, Path: # > paths > / > get > responses > 300 > content > application/json > examples > foo
3. File: api-with-examples.json , Line No: 75, Line Pos: 26 - Line No: 75, Line Pos: 27, Path: # > paths > /v2 > get > responses > 200 > content > application/json > examples > foo
4. File: api-with-examples.json , Line No: 124, Line Pos: 26 - Line No: 124, Line Pos: 27, Path: # > paths > /v2 > get > responses > 203 > content > application/json > examples > foo