From bbd3a6151c0dc3a5e814b6353d49183f444234a1 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 13 Dec 2021 15:11:01 -0600 Subject: [PATCH 1/3] docs: add docs on validation, fix TOC --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index db0a87237..7941246bf 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ * [Authentication](#authentication) * [Usage](#usage) * [Common options](#common-rdme-options) - * [Swagger / OpenAPI](#swagger-/-openapi) + * [OpenAPI / Swagger](#openapi--swagger) * [Docs](#docs) * [Versions](#versions) * [Opening a Project](#open) @@ -69,6 +69,13 @@ rdme openapi [path-to-file.json] --version={project-version} rdme openapi [path-to-file.json] --id={existing-id} --version={project-version} ``` +#### Validating an API Definition +You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition. + +```sh +rdme validate [path-to-file.json] +``` + #### Omitting the File Path If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. We will then look for a file with the following names, and upload that: `openapi.json`, `openapi.yaml`, `swagger.json`, and `swagger.yaml`. From 1d987f02dc59a846fd538483f4522b77e6dad6d3 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 13 Dec 2021 15:14:04 -0600 Subject: [PATCH 2/3] chore: move validation subsection to bottom of openapi section --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 7941246bf..7165090ad 100644 --- a/README.md +++ b/README.md @@ -69,18 +69,18 @@ rdme openapi [path-to-file.json] --version={project-version} rdme openapi [path-to-file.json] --id={existing-id} --version={project-version} ``` -#### Validating an API Definition -You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition. +#### Omitting the File Path +If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. We will then look for a file with the following names, and upload that: `openapi.json`, `openapi.yaml`, `swagger.json`, and `swagger.yaml`. ```sh -rdme validate [path-to-file.json] +rdme openapi ``` -#### Omitting the File Path -If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. We will then look for a file with the following names, and upload that: `openapi.json`, `openapi.yaml`, `swagger.json`, and `swagger.yaml`. +#### Validating an API Definition +You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition. ```sh -rdme openapi +rdme validate [path-to-file.json] ``` ### Docs From d3ba0e6a65ba55768698e2e7f73f6aeeb6a4a907 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 13 Dec 2021 15:16:38 -0600 Subject: [PATCH 3/3] docs: add YAML callout --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 7165090ad..c3b284a08 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,8 @@ If you wish to get more information about any command within `rdme`, you can exe ### OpenAPI / Swagger ReadMe supports [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md). +The following examples use JSON files, but we support API Definitions that are written in either JSON or YAML. + > ℹ️ Note that the `rdme openapi` command supports both OpenAPI and Swagger API definitions. The `rdme swagger` command is an alias for `rdme openapi` and is deprecated. #### Uploading a New API Definition to ReadMe