search

OAI / OpenAPI-Style-Guide

How to (and how not to) refer to the OAI in meetups, interviews, casual conversations, the settling of bar bets, and for conference presentations.
Apache License 2.0
207 stars 46 forks source link

Terminology explanation in README #32

Open dret opened 1 month ago

dret commented 1 month ago

Currently the README contains this:

Specification: for example "Can you send me your specification?" (may be abbreviated less formally as "spec")

It seems like this either refers to an older use of terms when it was ok to call a "definition" a "specification". Or if it really means that I am asking somebody to send me the OpenAPI specification, then this may not be the most helpful example. What about:

Specification: for example "My OpenAPI document conforms to the OpenAPI specification version 3.1.0"

handrews commented 1 month ago

We should definitely add "OpenAPI Description" (OAD) to the style guide as that's what we settled on calling the things that people write that conform to the OpenAPI Specification (OAS). We have an official glossary that defines these terms and the style guide should match its usage. The 3.0.4, 3.1.1, and 3.20 releases will use OpenAPI Description and OAD in their text.