update Open Source Docs from Roblox internal teams

Author: rbx-open-source-docs[bot]

content/common/navigation/cloud/reference.yaml

@@ -10,6 +10,8 @@ navigation:
     path: /cloud/reference/errors
   - title: OAuth 2.0
     path: /cloud/reference/oauth2
+  - title: OpenAPI Descriptions
+    path: /cloud/reference/openapi
   - heading: v2 Resources
   - title: All Cloud API
     path: /cloud/reference

content/en-us/cloud/open-cloud/index.md

@@ -28,6 +28,6 @@ The legacy APIs, no matter which types of authentication they support, can incor
 
    See the documentation for how to use [API keys](api-keys.md) or [OAuth 2.0](oauth2-overview.md). API keys are the easiest way to get started.
 
-1. Use a tool like [Postman](https://www.postman.com) or the [OAuth 2.0 sample app](oauth2-sample.md) to test API calls.
+1. Test API calls using tools like [Postman](https://www.postman.com) with [OpenAPI descriptions](../reference/openapi.md) and the [OAuth 2.0 sample app](oauth2-sample.md).
 1. Review the [resource guides](experience-notifications.md) for end-to-end walkthroughs of using certain APIs.
 1. See the Open Cloud [reference documentation](../reference/index.md) for the full list of v1 and v2 resources, [common API patterns](../reference/patterns.md), and [types](../reference/types.md).

content/en-us/cloud/reference/index.md

@@ -11,5 +11,6 @@ The **Common Components** section of the reference documentation includes concep
 - [Patterns](../../cloud/reference/patterns.md) - Special considerations and patterns for making requests and handling responses.
 - [Types](../../cloud/reference/types.md) - How to handle common types used by Open Cloud in requests and responses.
 - [Errors](../../cloud/reference/errors.md) - Handling errors when working with resources.
+- [OpenAPI Descriptions](../../cloud/reference/openapi.md) - Streamline development with OpenAPI descriptions of Open Cloud APIs.
 
 Each page in the **Resources** section represents a resource and includes all available operations for that resource.

content/en-us/cloud/reference/openapi.md

@@ -0,0 +1,65 @@
+---
+title: OpenAPI Descriptions
+description: Provides links to the Open Cloud JSON files that are compliant to the OpenAPI Specification, explains their use cases, and outlines additional information.
+---
+
+The reference pages in the **Resources** section are rendered from JSON files that are [OpenAPI descriptions](https://learn.openapis.org/glossary.html). These files use [version 3.0.4](https://spec.openapis.org/oas/v3.0.4) of the OpenAPI specification.
+
+These files are open source and can be used with tools like the [Swagger Editor](https://editor.swagger.io/) and [Postman](https://www.postman.com/) to test API calls and help streamline development.
+
+These OpenAPI descriptions are still under active development and may contain issues. The pages under the **Resources** section are the official reference.
+
+## OpenAPI Description Files
+
+OpenAPI description files are available at the following locations within the [creator-docs](https://github.com/Roblox/creator-docs/tree/main/content/en-us/reference/cloud) repository:
+
+```text
+# All V2 Resources
+https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/cloud.docs.json
+
+# V1 Assets
+https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/assets/v1.json
+
+# V1 Ordered Data Stores
+https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/datastores-api/ordered-v1.json
+
+# V1 Standard Data Stores
+https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/datastores-api/v1.json
+
+# V1 Messaging
+https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/messaging-service/v1.json
+
+# V1 Universes
+https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/universes-api/v1.json
+```
+
+### Vendor Extensions
+
+Roblox uses [specification extensions](https://spec.openapis.org/oas/v3.0.4#specification-extensions) to extend the OpenAPI specification. These extensions represent information that the specification doesn't capture by default. Extensions may appear throughout the file where allowed by the OpenAPI specification.
+
+The majority of these specification extensions are experimental. The extensions used are subject to change without notice in favor of fields found within the official OpenAPI specification.
+
+<Alert severity="info">
+The OpenAPI descriptions for V1 and V2 resources utilitize distinct specification extensions due to underlying implementation differences.
+</Alert>
+
+**V1 Resource Specification Extensions**
+
+| Extension                                       	| Location         	| Description                                                                                     	|
+|-------------------------------------------------	|------------------	|-------------------------------------------------------------------------------------------------	|
+| `x-roblox-cloud-api-operation`                  	| Operation Object 	| Boolean. Whether the operation is an Open Cloud operation.                                      	|
+| `x-roblox-cloud-api-operation-name`             	| Operation Object 	| String. The name of the operation.                                                              	|
+| `x-roblox-cloud-api-operation-code-samples`     	| Operation Object 	| Object. A list of code samples, an object with the language/title and the corresponding script. 	|
+| `x-roblox-cloud-api-operation-throttling-limit` 	| Operation Object 	| Object. The throttling limits for the operation.                                                	|
+
+**V2 Resource Specification Extensions**
+
+| Extension                             	| Location         	| Description                                                                                                   	|
+|---------------------------------------	|------------------	|---------------------------------------------------------------------------------------------------------------	|
+| `x-categories`                        	| OpenAPI Object   	| List of strings. All resource categories.                                                                     	|
+| `x-visibility`                        	| Operation Object 	| Boolean. The visibility of the operation.                                                                     	|
+| `x-roblox-docs`                       	| Operation Object 	| Object. Associates an operation with a category and resource.                                                 	|
+| `x-long-running-operation-parameters` 	| Operation Object 	| Object. References the metadata and response for the operation's long running response.                       	|
+| `x-oneOf`                             	| Schema Object    	| Object. Each field contains a list of properties in the schema. Only one of the properties should be present. 	|
+| `x-resource`                          	| Schema Object    	| Boolean. Whether the schema is a resource.                                                                    	|
+| `x-immutable`                         	| Schema Object    	| Boolean. Whether the schema is immutable.                                                                     	|

content/en-us/production/promotion/referral-system.md

@@ -57,7 +57,7 @@ function onPlayerAdded(player)
     local referredByPlayerId = joinData.ReferredByPlayerId
 
     -- Check if the player was invited through a referral
-    if referredByPlayerId then
+    if referredByPlayerId and referredByPlayerId ~= 0 then
         -- Fire the referral event to the client, passing the inviter's ID
         referrerEvent:FireClient(player, referredByPlayerId)
 
@@ -88,7 +88,7 @@ function onPlayerAdded(player)
     local referredByPlayerId = joinData.ReferredByPlayerId
 
     -- Check if the player was invited through a referral
-    if referredByPlayerId then
+    if referredByPlayerId and referredByPlayerId ~= 0 then
         -- Fire the referral event to the client, passing the inviter's ID
         referrerEvent:FireClient(player, referredByPlayerId)
 
@@ -130,7 +130,7 @@ function onPlayerAdded(player)
     local referredByPlayerId = joinData.ReferredByPlayerId
 
     -- Check if the player was invited and has not already used a referral
-    if referredByPlayerId and not referredPlayers[player.UserId] then
+    if referredByPlayerId and referredByPlayerId ~= 0 and not referredPlayers[player.UserId] then
         -- Mark the player as referred
         referredPlayers[player.UserId] = true
 

content/en-us/reference/cloud/README.md

@@ -1,6 +1,6 @@
 # Open Cloud Reference
 
-The Open Cloud V2 reference documentation at [https://create.roblox.com/docs/cloud/reference](https://create.roblox.com/docs/cloud/reference) is rendered from `cloud.docs.json`. This file uses a custom JSON format that is similar, but not identical to the OpenAPI Specification (OAS).
+The Open Cloud V2 reference documentation at [https://create.roblox.com/docs/cloud/reference](https://create.roblox.com/docs/cloud/reference) is rendered from `cloud.docs.json`. This file uses OpenAPI specification (OAS) version 3.0.4.
 
 - Because the content in `cloud.docs.json` is generated from source files, we don't accept pull requests on it.
 - We **do** accept pull requsts on the V1 reference documentation, but formatting the content and modifying the `curl` commands can be a real challenge.