The description of each API should be one to three paragraphs at the most, covering the business details of what an API delivers. Keep the technical details part of the OpenAPI info description, and make the API description something that will speak to what leadership and business stakeholders will be needing.
The API description is what will show in directories, catalogs, and be indexed by search engines when publicly available. Keep in mind that the individual who is searching for an API might not always be an engineering, helping keep API products accessible by other business stakeholders involved with consuming APIs in a variety of applications.
Write your API descriptions as you would any other marketing content, and keep focused on the business value of an API. The description will be used as part of distribution to portals, inclusion as part of documentation, but also likely to be distributed and federated using the underlying APIs.json contracts that include an API as part of it’s definition.