When a user would like to leverage your API having it advertised in the OpenAPI format make it very easy to understand and leverage.

There are tool in development which allow the automatic generation of a code based on this spec: https://github.com/OpenAPITools/openapi-generator

An example of a spec can be seen at https://developer.shodan.io/api. It can be written in json or yml. Here is an example of it in json: https://developer.shodan.io/api/openapi.json

It allows the creation of attractive interactive docs which can be used to execute the api directly.

It can be edited and validated in a number of ways
- online editor/ validator: https://editor.swagger.io/
- docker validator: https://hub.docker.com/r/swaggerapi/swagger-editor/

It provides a high level abstraction for the API complete with data types and logic.
Overview: https://swagger.io/docs/specification/about
Details specification is available here: https://spec.openapis.org/oas/latest.html