Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Terminology explanation in README #32

Open
dret opened this issue Jun 4, 2024 · 1 comment
Open

Terminology explanation in README #32

dret opened this issue Jun 4, 2024 · 1 comment

Comments

@dret
Copy link

dret commented Jun 4, 2024

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
Copy link
Member

handrews commented Jun 5, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants