By the way, my project is developing an API, in addition to coding, I am also supporting the Client to create documents, today I take the risk to learn a little concept of API, API document, Swagger, Basic Structure … synthesized in this paragraph. Hope the basic information below will be useful for newbies like me
The article uses the following sources:
https://quantrimang.com/giao-dien-lap-trinh-ung-dung-api-la-gi-148288
https://swagger.io/blog/api-documentation/what-is-api-documentation-and-why-it-matters/
https://swagger.io/docs/specification/2-0/basic-structure/
https://swagger.io/resources/articles/difference-between-api-documentation-specification/
First of all, we will find out what an API is.
What is API?
API stands for Application Programming Interface, a middleware that allows connection with other libraries and applications.
When using an application on a mobile phone, the application connects to the Internet and sends the data to the server. The server then retrieves that data, interprets it, performs the necessary actions, and sends it back to the phone. The app will then interpret that data and present the information you want in a readable way.
For ease of understanding, let’s take a familiar example below.
Imagine, in a restaurant, you are the customer and the kitchen is the “system” that prepares your menu. What is missing here is an important link to convey a customer’s request to the kitchen and deliver the food to the table for them. This important link is the waiter or the API. The waiter – API is the messenger, will take the order and convey it back to the kitchen – the system. Once the food is ready, the waiter will deliver it to the customer.
APIs and documentation types
API Documentation
API Document is the reference guide for API – Helping API users know how to use API effectively. API documentation is usually intended for programmers, helping the programmer read and understand; hence it is extremely important to create a well-designed, comprehensive, and traceable API documentation.
The API Document contains tutorials on how to effectively use and integrate with an API. It is a concise document, containing all the information required to work with the API, with details about functions, class (class), return type, Arguments (parameters), … are supported by tutorials and examples.
The API Document documentation is typically done using the common text editor, content creation, and maintenance tools. API description formats like the OpenAPI / Swagger Specification automate the document processing, making it easier for groups to create and maintain them.
So what is a good API documentation?
A good API documentation is evaluated in many respects, hard to list all here. However, one thing is for sure, the API documentation is only considered good when it includes both quick instructions and detailed instructions; in addition, it must be highly interactive documentation so the programmer can test the API calls.
The API documentation should provide examples of every call, every parameter, and response for each call. It must include sample source code for commonly used languages like Java, JavaScript, PHP, and Python. Also, the documentation should provide an explanation for each API request and examples of error messages.
API Specification
API specification is a term commonly used interchangeably with API definition. Although these two terms have many similarities, in reality they are different entities.
API specification provides extensive understanding of how one API works and how APIs bind to other APIs. It explains how the API works and the expected results using the API.
The API specification documentation includes many API objects, values and parameters, how objects are invoked, and the functionality of each. In addition, the API specification documentation also shows relationships between objects and how each can be used.
API Definition
API definition is similar to the API specification in that it provides an understanding of how an API is organized and how the API works. However, API definition is geared towards using device APIs rather than human-developers use APIs.
The API definition documentation provides information about how the API works, how it associates with other APIs, and the expected results in a machine-readable format. It focuses on defining the API and outlining the structure of the API.
This documentation is used as the basis for automation tools like API documentation automation (SwaggerHub and Swagger Inspector), code samples, and SDK (REST United and SwaggerHub).
Difference between API Documentation, Specification, and Definition
The API documentation, API specification, and API definition are all related, but they are different entities. And each type of document serves a different important purpose.
API documentation tells developers and other API users how to use the API.
The API specification documentation provides a broad understanding of the API’s functionality and expected results. Specification is mainly about the design of the API or the philosophy of the API. API design and functionality are key factors when choosing to integrate an API with an application.
And finally, the API definition document is geared towards using the API of a machine device, providing a format that the device is readable for use by automated tools such as automatic API documentation. API documentation) and SDK generators.
Get a deeper understanding of API Document
The importance of API Document
Interestingly, programmers often pay little attention to the API document when running the code. In fact, implementing code is a lot easier than writing a good API documentation.
API documentation directly affects API integration and usage. Your product may function best, but no one will use it if they don’t know how to use it.
It can be said that API document is the foundation to help programmers have a good experience.
What is Swagger?
Swagger is a tool that allows to describe the structure of APIs so that machines can read them. By reading the API structure, Swagger is able to dynamically generate a beautiful and interactive API document.
In addition, Swagger can also automatically generate client libraries as well as automated testing by requiring the API to return a YAML or JSON containing a detailed description of the entire API. This file is essentially a list of API resources that conform to the OpenAPI specification, which includes information like:
- What activities does the API support?
- What parameters does the API have? Returns what?
- Does the API need any authorization?
- Terms, contact information, and license to use the API
Swagger specs can be created manually or automatically from annotations in source code. Check out swagger.io/open-source-integrations for a list of tools that allow Swagger creation from code.
Basic structure of Swagger Specs
Swagger definitions can be written in JSON or YAML. The following section will take the YAML examples, similar to JSON.
A sample Swagger specification written in YAML would look like this:
Metadata
All Swagger specifications start with Swagger version, where 2.0 is the latest version.
The Swagger version defines the overall structure of the API specifications – what is included in and how they are described.
After that, you need to specify API info , including title , description (optional description), and version (API version, not Swagger version).
version can be a random string. We can use major.minor.patch or an arbitrary format like 1.0-beta or 2016.11.15 .
description is multiline and supports GitHub Flavored Markdown for rich text presentation.
info also supports other content such as contact information, licenses …
Base URL
The base URL for all API calls uses schemes , host and basePath .
Each API path is related to the base URL, for example / users is actually https://api.example.com/v1/users .
Consumes, Produces
Consumes and Produces define the MiME types supported by the API.
Paths
The paths section identifies the individual endpoints in the API and the HTTP methods supported by these endpoints.
For example, GET / users could be described as follows:
Parameters
Operations can have parameters passed via URL ( /users/{userId} ), query string ( /users?role=admin ), title ( X-CustomHeader: Value ), and request content. .
Responses
For each operation, we can define possible status codes, such as 200 OK or 404 Not Found, and the schema of the response content.
Schema can be defined inline or referenced from external definition via $ref . In addition, we can also provide example responses for each content type.
Input and Output
The definitions section allows to define the general data structure used in the API. This data structure can be referenced via $ref whenever a schema is needed for both the request body and the response body.
For example, with this JSON object:
can be represented in the following format:
And then referenced in the request body schema, the response body schema is as follows:
Authentication
The keywords securityDefinitions and security used to describe the authentication methods used in the API.
Supported authentication methods include:
- Basic authentication
- API key
- OAuth 2
-The end-