feat(docs): add API Reference config documentation (#4379)

* progress so far

* update docs

* paginated docs

* add fix

* remove words

* API reference docs update

---------

Co-authored-by: Danny Sheridan <83524670+dannysheridan@users.noreply.github.com>

Author: chdeskur

fern/docs.yml

@@ -273,7 +273,7 @@ navigation:
 
       - section: API References
         contents:
-          - page: Generate API reference
+          - page: Generate API Reference
             icon: fa-regular fa-gear-code
             path: ./pages/fern-docs/content/generate-api-ref.mdx
             slug: generate-api-ref
@@ -283,9 +283,9 @@ navigation:
           - page: Endpoint errors
             icon: fa-regular fa-exclamation-triangle
             path: ./pages/fern-docs/config/endpoint-errors.mdx
-          - page: Reorder API Reference pages
+          - page: Customize API Reference layout
             icon: fa-regular fa-arrow-up-arrow-down
-            path: ./pages/fern-docs/content/reorder-api-ref.mdx
+            path: ./pages/fern-docs/content/customize-api-ref.mdx
           - page: Write markdown in API Reference
             icon: fa-regular fa-pencil
             path: ./pages/fern-docs/content/api-ref-content.mdx

fern/pages/api-definition/fern-definition/api-yml/overview.mdx

@@ -28,7 +28,7 @@ name: api
 
 ## API description
 
-You can define a top level API description. This description will come through in the OpenAPI spec and Postman collection.
+You can define a top level API description. This description will come through in the OpenAPI Specification and Postman collection.
 
 <CodeBlock title="api.yml">
 ```yaml {2-4}

fern/pages/api-definition/fern-definition/audiences.mdx

@@ -3,7 +3,7 @@ title: Audiences in Fern Definition
 subtitle: Use audiences in your Fern Definition to segment your API for different groups of consumers.
 ---
 
-Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. You can use [audiences in your OpenAPI specification](/learn/api-definition/openapi/extensions#audiences), too. 
+Audiences are a useful tool for segmenting your API for different consumers. You can configure your Fern Docs to publish documentation specific to an `Audience`. You can use [audiences in your OpenAPI Specification](/learn/api-definition/openapi/extensions#audiences), too. 
 
 Common examples of audiences include:
 

fern/pages/api-definition/fern-definition/examples.mdx

@@ -1,6 +1,6 @@
 ---
 title: Examples in Fern Definition 
-subtitle: Use Fern Definition to add API examples that are shown in comments of SDKs, API reference documentation, and a Postman collection.
+subtitle: Use Fern Definition to add API examples that are shown in comments of SDKs, API Reference documentation, and a Postman collection.
 ---
 
 You can add examples for types and endpoints. Examples are shown as

fern/pages/api-definition/introduction/what-is-an-api-definition.mdx

@@ -17,7 +17,7 @@ Fern integrates with several API definition formats:
     Formerly known as Swagger, [OpenAPI](https://swagger.io/specification/) is the most popular API definition format.
     OpenAPI can be used to document RESTful APIs and is defined in a YAML or JSON file.
 
-    Check out an example OpenAPI spec for the Petstore API [here](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
+    Check out an example OpenAPI Specification for the Petstore API [here](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
 
     ```yaml maxLines={0}
     openapi: 3.0.2
@@ -218,7 +218,7 @@ Fern integrates with several API definition formats:
 ## Why create an API Definition ? 
 
 Once you have an API definition, Fern will use it as an input to generate artifacts 
-like SDKs and API reference documentation. Every time you update the API definition,
+like SDKs and API Reference documentation. Every time you update the API definition,
 you can regenerate these artifacts and ensure they are always up-to-date.
 
 <CardGroup cols={2}>

fern/pages/api-definition/introduction/what-is-the-fern-folder.mdx

@@ -18,8 +18,8 @@ fern/
     └─ imdb.yml
 ```
 
-If you want to intialize Fern with an OpenAPI spec, run `fern init --openapi path/to/openapi` instead.
-```bash
+If you want to intialize Fern with an OpenAPI Specification, run `fern init --openapi path/to/openapi` instead.
+```yaml
 fern/
   ├─ fern.config.json
   ├─ generators.yml

fern/pages/api-definition/openapi/extensions/others.mdx

@@ -472,11 +472,11 @@ shown in the third tab.
 
 ## Embedding extensions
 
-If instead of overlaying your extensions within an overrides file, as mentioned above. Certain frameworks that generate OpenAPI specs make it easy to embed extensions directly from code.
+If instead of overlaying your extensions within an overrides file, as mentioned above. Certain frameworks that generate OpenAPI Specifications make it easy to embed extensions directly from code.
 
 ### FastAPI
 
-Please view our page on [FastAPI](/learn/api-definition/openapi/frameworks/fastapi) for more information on how to extend your OpenAPI spec within FastAPI.
+Please view our page on [FastAPI](/learn/api-definition/openapi/frameworks/fastapi) for more information on how to extend your OpenAPI Specification within FastAPI.
 
 ## Request + response examples
 

fern/pages/api-definition/openapi/openapi-overview.mdx

@@ -1,16 +1,16 @@
 ---
 title: Use OpenAPI for your API definition
-description: An overview of how to define your API using an OpenAPI specification, then use Fern to generate SDKs and API reference documentation for the API.
+description: An overview of how to define your API using an OpenAPI Specification, then use Fern to generate SDKs and API Reference documentation for the API.
 ---
 
-Fern supports the use of the [OpenAPI specification](https://www.openapis.org/) (up to and including version 3.1) to define APIs. Alternatively, you can use Fern's simpler format called [Fern Definition](/learn/api-definition/fern/overview).
+Fern supports the use of the [OpenAPI Specification](https://www.openapis.org/) (up to and including version 3.1) to define APIs. Alternatively, you can use Fern's simpler format called [Fern Definition](/learn/api-definition/fern/overview).
 
-Fern generates SDKs and API reference documentation from your OpenAPI spec. Get started by creating a `fern/` project through one of our [Quickstarts](/learn/docs/getting-started/quickstart), then replace the file in the `fern/openapi/` folder with your own. You can use either JSON or YAML for your file.
+Fern generates SDKs and API Reference documentation from your OpenAPI Specification. Get started by creating a `fern/` project through one of our [Quickstarts](/learn/docs/getting-started/quickstart), then replace the file in the `fern/openapi/` folder with your own. You can use either JSON or YAML for your file.
 
-Run `fern check` to validate the OpenAPI spec. Resolve any errors.
+Run `fern check` to validate the OpenAPI Specification. Resolve any errors.
 Having trouble? Reach out in the [Fern Discord server](https://discord.com/invite/JkkXumPzcG).
 
 If you're having trouble understanding the errors, run the command [`fern write-definition`](/learn/cli-api/cli-reference/commands#fern-write-definition).
-This command will convert your OpenAPI spec into a Fern Definition.
+This command will convert your OpenAPI Specification into a Fern Definition.
 
 If there are no errors, you can run [fern generate](/learn/cli-api/cli-reference/commands#fern-generate) to generate SDKs or [fern generate --docs](/learn/cli-api/cli-reference/commands#fern-generate) to generate docs.

fern/pages/api-definition/openapi/overrides.mdx

@@ -3,11 +3,11 @@ title: How to use OpenAPI Overrides
 subtitle: Use overrides to customize user-facing documentation fields, examples, and naming.
 ---
 
-When you generate your OpenAPI from server code, you may want to further customize portions of your OpenAPI spec. You can do this with OpenAPI Overrides. When you run `fern generate`, Fern will automatically apply these overrides on top of your OpenAPI spec.
+When you generate your OpenAPI from server code, you may want to further customize portions of your OpenAPI Specification. You can do this with OpenAPI Overrides. When you run `fern generate`, Fern will automatically apply these overrides on top of your OpenAPI Specification.
 
 ## How to use OpenAPI Overrides
 
-To use OpenAPI Overrides, create a file named `openapi-overrides.yml`. You can put the file anywhere in your project. This file contains the overrides you want to apply to your OpenAPI spec. For more on the extensions available, visit our page on [OpenAPI Extensions](https://buildwithfern.com/learn/api-definition/openapi/extensions).
+To use OpenAPI Overrides, create a file named `openapi-overrides.yml`. You can put the file anywhere in your project. This file contains the overrides you want to apply to your OpenAPI Specification. For more on the extensions available, visit our page on [OpenAPI Extensions](https://buildwithfern.com/learn/api-definition/openapi/extensions).
 
 ### Example
 

fern/pages/api-definition/openapi/server-frameworks/fastapi.mdx

@@ -1,6 +1,6 @@
 ---
 title: FastAPI Instrumentation
-description: Learn about best practices for creating rich OpenAPI specs when instrumenting FastAPI applications.
+description: Learn about best practices for creating rich OpenAPI Specifications when instrumenting FastAPI applications.
 ---
 
 [FastAPI](https://fastapi.tiangolo.com/) is a popular Python web framework developed by [tiangolo](https://github.com/tiangolo).
@@ -9,38 +9,38 @@ The offering brands itself as
 
 > FastAPI is a modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints.
 
-FastAPI plays very nicely with Fern because it has the power to output OpenAPI specs! Below we'll outline some tips for generating a rich OpenAPI with FastAPI.
+FastAPI plays very nicely with Fern because it has the power to output OpenAPI Specifications! Below we'll outline some tips for generating a rich OpenAPI with FastAPI.
 
 
 ## OpenAPI generation
 
-By default, FastAPI will generate an OpenAPI spec for you based on your routes and your data models! You can access this spec by visiting `/docs` on your FastAPI server.
+By default, FastAPI will generate an OpenAPI Specification for you based on your routes and your data models! You can access this spec by visiting `/docs` on your FastAPI server.
 
-If you are not seeing any OpenAPI spec (or the Swagger UI), you may need to review your FastAPI server configuration as the path may have been changed, or completely omitted.
+If you are not seeing any OpenAPI Specification (or the Swagger UI), you may need to review your FastAPI server configuration as the path may have been changed, or completely omitted.
 
 ```python {6-8}
 from fastapi import FastAPI
 
 ...
 
 FastAPI(
-    openapi_url="/openapi.json",  # <-- this is the file and URL needed to access the OpenAPI spec, `docs_url` and `redoc_url` are convenient wrappers that display the file in a UI!
-    docs_url="/docs",             # <-- this is the URL to access the Swagger UI, which will point to your OpenAPI spec
-    redoc_url="/redoc"            # <-- this is the URL to access the ReDoc UI, which will point to your OpenAPI spec
+    openapi_url="/openapi.json",  # <-- this is the file and URL needed to access the OpenAPI Specification, `docs_url` and `redoc_url` are convenient wrappers that display the file in a UI!
+    docs_url="/docs",             # <-- this is the URL to access the Swagger UI, which will point to your OpenAPI Specification
+    redoc_url="/redoc"            # <-- this is the URL to access the ReDoc UI, which will point to your OpenAPI Specification
 )
 ```
 
 ## Specifying servers
 
-Fern will automatically generate clients that point to the servers you configure within your OpenAPI spec, so it's important to specify the servers that your API will be hosted on.
+Fern will automatically generate clients that point to the servers you configure within your OpenAPI Specification, so it's important to specify the servers that your API will be hosted on.
 
 ```python {5}
 from fastapi import FastAPI
 
 ...
 
 app = FastAPI(servers=[{"url": "http://prod.test.com", "description": "Production server"}])
-# This creates the following server object in your OpenAPI spec:
+# This creates the following server object in your OpenAPI Specification:
 # "servers":[{"url":"http://prod.test.com","description":"Production server"}],
 ```
 
@@ -52,7 +52,7 @@ Below, we've annotated a "good" route within FastAPI that has it's typings as we
 ```python {5-9}
 @router.post(
     "/your/post/endpoint",
-    response_model=YourResponseModel,            #  <-- with FastAPI, it is important to specify your response model so that it comes through to the OpenAPI spec
+    response_model=YourResponseModel,            #  <-- with FastAPI, it is important to specify your response model so that it comes through to the OpenAPI Specification
     summary="Get some response for your req",    #  <-- if you'd like to add a description to your endpoint, you can do so here
     openapi_extra={                              #  <-- finally, you can add in your Fern extensions here, these extensions will produce SDK code that looks something like: `client.endpoints.create(...)` in python
         "x-fern-sdk-method-name": "create",
@@ -89,4 +89,4 @@ class MyObject(BaseModel):
 
 ## Additional customization
 
-FastAPI has a lot of flexibility in how you can customize your OpenAPI spec. Please refer to the [FastAPI documentation](https://fastapi.tiangolo.com/how-to/extending-openapi/#modify-the-openapi-schema) for more information.
+FastAPI has a lot of flexibility in how you can customize your OpenAPI Specification. Please refer to the [FastAPI documentation](https://fastapi.tiangolo.com/how-to/extending-openapi/#modify-the-openapi-schema) for more information.