diff --git a/documentation/commands/openapi.md b/documentation/commands/openapi.md index c5dc436a8..df458f17b 100644 --- a/documentation/commands/openapi.md +++ b/documentation/commands/openapi.md @@ -3,119 +3,11 @@ Manage your API definition (e.g., syncing, validation, analysis, conversion, etc.). Supports OpenAPI, Swagger, and Postman collections, in either JSON or YAML formats. -* [`rdme openapi [SPEC]`](#rdme-openapi-spec) * [`rdme openapi convert [SPEC]`](#rdme-openapi-convert-spec) * [`rdme openapi inspect [SPEC]`](#rdme-openapi-inspect-spec) * [`rdme openapi reduce [SPEC]`](#rdme-openapi-reduce-spec) * [`rdme openapi validate [SPEC]`](#rdme-openapi-validate-spec) -## `rdme openapi [SPEC]` - -Upload, or resync, your OpenAPI/Swagger definition to ReadMe. - -``` -USAGE - $ rdme openapi [SPEC] --key [--version ] [--id ] [--title ] - [--workingDirectory ] [--github] [--dryRun] [--useSpecVersion] [--raw] [--create | --update] - -ARGUMENTS - SPEC A file/URL to your API definition - -FLAGS - --create Bypasses the create/update prompt and creates a new API definition in ReadMe. - --dryRun Runs the command without creating/updating any API Definitions in ReadMe. Useful for - debugging. - --github Create a new GitHub Actions workflow for this command. - --id= Unique identifier for your API definition. Use this if you're re-uploading an existing API - definition. - --key= (required) An API key for your ReadMe project. Note that API authentication is required - despite being omitted from the example usage. See our docs for more information: - https://github.com/readmeio/rdme/tree/v9#authentication - --raw Return the command results as a JSON object instead of a pretty output. - --title= An override value for the `info.title` field in the API definition - --update Bypasses the create/update prompt and automatically updates an existing API definition in - ReadMe. - --useSpecVersion Uses the version listed in the `info.version` field in the API definition for the project - version parameter. - --version= ReadMe project version - --workingDirectory= Working directory (for usage with relative external references) - -DESCRIPTION - Upload, or resync, your OpenAPI/Swagger definition to ReadMe. - - Locates your API definition (if you don't supply one), validates it, and then syncs it to your API reference on - ReadMe. - -EXAMPLES - This will upload the API definition at the given URL or path to your project and return an ID and URL for you to - later update your file, and view it in the client: - - $ rdme openapi [url-or-local-path-to-file] - - You can omit the file name and `rdme` will scan your working directory (and any subdirectories) for OpenAPI/Swagger - files. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments. - - $ rdme openapi - - If you want to bypass the prompt to create or update an API definition, you can pass the `--create` flag: - - $ rdme openapi [url-or-local-path-to-file] --version={project-version} --create - - This will edit (re-sync) an existing API definition (identified by `--id`) within your ReadMe project. **This is the - recommended approach for usage in CI environments.** - - $ rdme openapi [url-or-local-path-to-file] --id={existing-api-definition-id} - - Alternatively, you can include a version flag, which specifies the target version for your file's destination. This - approach will provide you with CLI prompts, so we do not recommend this technique in CI environments. - - $ rdme openapi [url-or-local-path-to-file] --id={existing-api-definition-id} - - If you wish to programmatically access any of this script's results (such as the API definition ID or the link to - the corresponding docs in your dashboard), supply the `--raw` flag and the command will return a JSON output: - - $ rdme openapi openapi.json --id={existing-api-definition-id} --raw - - You can also pass in a file in a subdirectory (we recommend running the CLI from the root of your repository if - possible): - - $ rdme openapi example-directory/petstore.json - - By default, `rdme` bundles all references with paths based on the directory that it is being run in. You can - override the working directory using the `--workingDirectory` option, which can be helpful for bundling certain - external references: - - $ rdme openapi petstore.json --workingDirectory=[path to directory] - - If you wish to use the version specified in the `info.version` field of your OpenAPI definition, you can pass the - `--useSpecVersion` option. So if the the `info.version` field was `1.2.3`, this is equivalent to passing - `--version=1.2.3`. - - $ rdme openapi [url-or-local-path-to-file] --useSpecVersion - - If there's only one API definition for the given project version to update, you can use the `--update` flag and it - will select it without any prompts: - - $ rdme openapi [url-or-local-path-to-file] --version={project-version} --update - -FLAG DESCRIPTIONS - --key= - - An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example - usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication - - ReadMe project API key - - --update Bypasses the create/update prompt and automatically updates an existing API definition in ReadMe. - - Note that this flag only works if there's only one API definition associated with the current version. - - --version= ReadMe project version - - If running command in a CI environment and this option is not passed, the main project version will be used. See our - docs for more information: https://docs.readme.com/main/docs/versions -``` - ## `rdme openapi convert [SPEC]` Converts an API definition to OpenAPI and bundles any external references.