|
1 | 1 | --- |
2 | | -title: OpenAPI descriptions |
3 | | -description: Provides links to the Open Cloud JSON files that are compliant to the OpenAPI Specification, explains their use cases, and outlines additional information. |
| 2 | +title: OpenAPI document |
| 3 | +description: Provides a link to a OpenAPI document for the Roblox Cloud APIs that is compliant to the OpenAPI specification. |
4 | 4 | --- |
5 | 5 |
|
6 | | -Some of the reference pages 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. |
| 6 | +Roblox publishes an [OpenAPI 3.0.4 document](https://spec.openapis.org/oas/v3.0.4) (formerly known as a Swagger file) that contains **all** of the Roblox Cloud APIs. You can find this file, `openapi.json`, in the open source [creator-docs](https://github.com/Roblox/creator-docs/tree/main/content/en-us/reference/cloud) repository. |
7 | 7 |
|
8 | | -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. |
| 8 | +You can use OpenAPI documents with tools like the [Swagger Editor](https://editor.swagger.io/) and [Postman](https://www.postman.com/) to test calls and help streamline development. Tools like [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) can also generate client libraries for your preferred programming languages. |
9 | 9 |
|
10 | | -These OpenAPI descriptions are still under active development and may contain issues. Use the reference and features section pages as official documentation. |
| 10 | +<Alert severity="warning"> |
| 11 | +This document is still under active development and may contain issues. Report a bug if you notice inaccurate information. |
| 12 | +</Alert> |
11 | 13 |
|
12 | | -## OpenAPI description files |
13 | | - |
14 | | -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: |
15 | | - |
16 | | -```text |
17 | | -# Open Cloud v2 |
18 | | -https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/cloud.docs.json |
19 | | -
|
20 | | -# Assets |
21 | | -https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/assets/v1.json |
22 | | -
|
23 | | -# Ordered Data Stores |
24 | | -https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/datastores-api/ordered-v1.json |
25 | | -
|
26 | | -# Standard Data Stores |
27 | | -https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/datastores-api/v1.json |
28 | | -
|
29 | | -# Messaging |
30 | | -https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/messaging-service/v1.json |
31 | | -
|
32 | | -# Place publishing |
33 | | -https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/universes-api/v1.json |
34 | | -``` |
| 14 | +<a href="https://github.com/Roblox/creator-docs/blob/main/content/en-us/reference/cloud/"> |
| 15 | + <Button variant="contained">Download openapi.json here</Button> |
| 16 | +</a><br /> |
35 | 17 |
|
36 | 18 | ### Vendor extensions |
37 | 19 |
|
38 | 20 | 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. |
39 | 21 |
|
40 | 22 | 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. |
41 | 23 |
|
42 | | -| Extension | Location | Description | |
43 | | -|------------------------------- |------------------ |---------------------------------------------------------------------------------------------------------------------------------------- | |
44 | | -| `x-roblox-extensions-version` | OpenAPI Object | A version string, using semantic versioning, that represents the versions of the extensions specified here and other common structures | |
45 | | -| `x-roblox-stability` | Operation Object | A string that represents an operation's stability level. | |
46 | | -| `x-roblox-deprecated` | Operation Object | An object that provides additional information related to an endpoint's deprecation status. | |
47 | | -| `x-roblox-alternatives` | Operation Object | An object that provides additional information related to an endpoint's alternatives. | |
48 | | -| `x-roblox-rate-limits` | Operation Object | An object that provides rate limiting information for an endpoint. | |
49 | | -| `x-roblox-scopes` | Operation Object | An object that provides the list of required, conditional, and optional scopes that are associated with an endpoint. | |
50 | | -| `x-roblox-engine-usability` | Operation Object | An object indicating the endpoint's usability with the Roblox engine. | |
51 | | - |
52 | | -In addition to these specification extensions, Open Cloud v2 APIs have a few additional extensions: |
53 | | - |
54 | | -**Open Cloud v2 specification extensions** |
55 | | - |
56 | | -| Extension | Location | Description | |
57 | | -|---------------------------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
58 | | -| `x-categories` | OpenAPI Object | List of strings. All resource categories. | |
59 | | -| `x-visibility` | Operation Object | Boolean. The visibility of the operation. | |
60 | | -| `x-roblox-docs` | Operation Object | Object. Associates an operation with a category and resource. | |
61 | | -| `x-long-running-operation-parameters` | Operation Object | Object. References the metadata and response for the operation`s long running response. | |
62 | | -| `x-aep-resource` | Schema Object | Object. An extension annotating the resource type. Has close compatibility to [AEP-4](https://aep.dev/4/#annotating-resource-types), one of the [API Enhancement Proposals](https://aep.dev/). | |
63 | | -| `x-oneOf` | Schema Object | Object. Each field contains a list of properties in the schema. Only one of the properties should be present. | |
64 | | -| `x-resource` | Schema Object | Boolean. Whether the schema is a resource. | |
65 | | -| `x-immutable` | Schema Object | Boolean. Whether the schema is immutable. | |
| 24 | +| Extension | Location | Description | |
| 25 | +| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- | |
| 26 | +| `x-roblox-extensions-version` | OpenAPI object | A version string, using semantic versioning, that represents the versions of the extensions specified here and other common structures | |
| 27 | +| `x-roblox-stability` | Operation object | A string that represents an operation's stability level. | |
| 28 | +| `x-roblox-deprecated` | Operation object | An object that provides additional information related to an endpoint's deprecation status. | |
| 29 | +| `x-roblox-alternatives` | Operation object | An object that provides additional information related to an endpoint's alternatives. | |
| 30 | +| `x-roblox-rate-limits` | Operation object | An object that provides rate limiting information for an endpoint. | |
| 31 | +| `x-roblox-scopes` | Operation object | An object that provides the list of required, conditional, and optional scopes that are associated with an endpoint. | |
| 32 | +| `x-roblox-engine-usability` | Operation object | An object indicating the endpoint's usability with the Roblox engine. | |
![rbx-open-source-docs[bot]](https://avatars.githubusercontent.com/in/357490?v=4&size=40){kind=avatar}
0 commit comments