diff --git a/introduction.md b/introduction.md index a962c4b..4d75ad7 100644 --- a/introduction.md +++ b/introduction.md @@ -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. @@ -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.