Instructor: So let's talk about OpenAPI.
So OpenAPI is the De-Facto standard for API documentation.
There are a few, but OpenAPI is a leader by far.
OpenAPI specifies a description format for REST API.
We will talk about the details of the format in a minute,
but before it, if the name OpenAPI is not familiar,
you have probably heard about Swagger.
Swagger is the original name of OpenAPI,
and the name was changed recently.
Okay, so what OpenAPI describes?
What contained in the format of OpenAPI?
So OpenAPI describes the endpoints,
and by endpoints, we usually mean the URL and the verb,
and the parameters, which are the parameters
that can be included in every API,
the authentication stream, if any
and some general information about the API,
like the publisher description, title, version, and so on.
Now, OpenAPI can be used to provide documentation
and the test bed for developers.
So what test bed is,
test bed is an automatically generated test client
for the REST API.
So if you provide documentation generated by OpenAPI,
then this documentation automatically creates
also a REST client that the developers
can use to test the API.
Now from my experience, this test bed is an amazing tool
in understanding exactly how to work with the API.
In addition, OpenAPI can generate client libraries.
So not only does it tell you how to use API
but you can also get from it a client library
in various platforms such as Java, .NET, Python, and more.
That will make the call to the API.
In addition to that,
OpenAPI can also generate the API itself.
This approach is called Design-First
and it means that you first write the documentation
using the OpenAPI platform,
and OpenAPI then generates the API to be exactly
compliant with the documentation that you just wrote.
This is a very interesting approach, I must admit.
I don't know of many organizations that use it, but again
keep it in mind and it's important to be familiar with it.
And of course OpenAPI can do much more than that.
Now,
the OpenAPI documentation can be automatically generated
and this is a preferred approach.
We will demonstrate it towards the end of this section
and it is compatible with many API platforms.
So you can assume that,
no matter what is your development platform,
you can automatically generate the OpenAPI documentation
from this platform.