Skip to content

fix: update broken link (fixes #70) #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 14, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,9 @@ title: Introduction
nav_order: 2
---


# Introduction

The **OpenAPI Specification** (**OAS**) allows the description of a remote API accessible through HTTP or HTTP-like protocols. This description, which may be stored as one or more documents (such as local files or HTTP-accessible network resources), is called an **OpenAPI Description** (**OAD**). This chapter explains why describing your API with an OAD is a good thing, and why it might interest you.
The **OpenAPI Specification** (**OAS**) allows the description of a remote API accessible through HTTP or HTTP-like protocols. This description, which may be stored as one or more documents (such as local files or HTTP-accessible network resources), is called an **OpenAPI Description** (**OAD**). This chapter explains why describing your API with an OAD is a good thing, and why it might interest you.

The concept of an "API" is described first and the advantages of describing APIs using a machine-readable format are introduced, followed by the benefits of using the OAS format. In the last section, the evolution of API descriptions is put into perspective with a brief historical summary.

Expand Down Expand Up @@ -54,7 +53,7 @@ The next section shows how some of these problems can be alleviated by specifyin

An **API description file** (sometimes called _contract_) is a **machine-readable** specification of an API. It should strive to be as **complete**, and **fully-detailed** as possible, although absolute completeness is not usually a requirement. Also, just like legal contracts, the more **unambiguous** it is, the more useful it becomes.

Its main advantage over documentation which only humans can read is that it enables **automated processing**, opening the door to the benefits listed at [the beginning of this guide](start-here).
Its main advantage over documentation which only humans can read is that it enables **automated processing**, opening the door to the benefits listed at [the beginning of this guide](/#advantages-of-using-openapi).

To begin with, documentation for humans including the list of available methods and their details can be easily generated from the API description file. Done as a step in the build process, this easily prevents out-of-sync docs.

Expand Down