Update overview.mdx for CLI overview

[minaelee]

For now, mostly just fixing a capitalization issue (first letter of a sentence not capitalized) and a broken link to the generators page.

Seems like this page could use further revision though. The section on generator schema seems out of place here and I would think it makes more sense on the generators page, or the fern generate page. The section on compilers could maybe go, too. The information on fern login seems germane (and could be expanded upon), and perhaps a link to the fern help page could be added along with note about ability to use --help flag for each command; also perhaps a section on logging.

[minaelee]

Forgot to mention that I changed:

Here are some examples of what the Fern compiler can output:
. . .
An OpenAPI Specification

to

An OpenAPI Description

Reason: According to The OpenAPI Initiative, the OpenAPI Specification (OAS) is the actual specification itself, whereas documents using specification to describe APIs are called OpenAPI Descriptions (OAD).
Source: https://learn.openapis.org/introduction.html and https://learn.openapis.org/specification/structure.html

[dannysheridan]

Sounds like OpenAPI Description is the term deemed by the OpenAPI Initiative to be accurate. However Stripe https://github.com/stripe/openapi calls it their Description an OpenAPI Spec and so does Twilio https://github.com/twilio/twilio-oai

[minaelee]

I looked into this further. First, I looked at what other major companies use. There's a wide range of terms in use including "OpenAPI document", "OpenAPI spec", "OAS document", "OAS file", "OpenAPI file", "API defined in OAS 3", "OAS definition", "OpenAPI definition", and so on.

I noticed that even the official spec at openapis.org uses the term "OpenAPI Document" instead of the "OpenAPI Description" term used in learn.openapis.org. I descended a rabbit hole that led me to a PR and a long Oct '23 discussion in the open-api Slack. That discussion ended with the OAI Technical Steering Committee agreeing on "OpenAPI Description (OAD)".

Other contenders in the discussion were "OpenAPI Document" and "OpenAPI Definition", but using "OpenAPI Specification" or "OpenAPI spec" to refer to a file that conforms to the spec seems to be universally considered incorrect by the OAI. GitHub is an example of an org that uses the OAI-preferred terminology. I would recommend regarding the OAI as the source of truth and going forward with "OpenAPI Description" and "OAD", or "OpenAPI Document" (which is conveniently also OAD) as a secondary choice.

[dannysheridan]

Thanks for diving into this. Given this ambiguity, my instinct is to go with what's most commonly used by devs. Pick the colloquially term, not necessarily the steering-committee-defined "right" term.

Github search results
openapi spec -> 4m
openapi description -> 2.5m
openapi definition -> 1.2m
openapi specification -> 0.9m

As a result, I think we should use openapi spec. Maybe we have a two or three sentence blurb in the docs explaining that all these things are referring to the same thing within Fern's documentation.

Curious for your thoughts!

[minaelee]

It's hard to gauge how many of the results from the github search for openapi spec refer to a file based on the specs vs the actual spec.

That said, I agree it seems to be in more common usage, and I can see the value in a descriptive approach vs prescriptive, and using a term more people may be familiar with/might search for. I like the idea of including an explanatory blurb somewhere.

Do you want to use "OpenAPI spec" or "OpenAPI Spec" across the board instead of "OpenAPI Specification"? This PR affected a line that said "An OpenAPI Specification" - did you want to use "An OpenAPI Spec" here, or perhaps "A file conforming to the OpenAPI spec"?

[dannysheridan]

I'm up for using OpenAPI specification across the board. I think there will not be ambiguity if we do so.

[dannysheridan]

I would do the same for Postman collection even though they officially call it a Postman Collection