From 768fc6050f372c54b9151123d422c0134213291b Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 25 Aug 2021 11:22:00 -0500 Subject: [PATCH 1/4] docs: title-case headings --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 1b241d038..da31e4a65 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ rdme login ## Usage If you wish to get more information about any command within `rdme`, you can execute `rdme help ` or `rdme --help`. You an also execute `rdme help` to see a global list of commands that `rdme` offers. -### Common `rdme` options +### Common `rdme` Options * `--key `: The API key associated with your ReadMe project. You can obtain this from your dashboard, or alternatively if you log in with `rdme login`, we will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`), saving you the hassle of having to supply this argument on commands that have it. * `--version `: Your project version. @@ -44,21 +44,21 @@ ReadMe supports both [Swagger 2.0](https://swagger.io/docs/specification/2-0/bas > ℹ️ Note that the `rdme swagger` command is also available alongside `rdme openapi` also supports both OpenAPI and Swagger API definitions. -#### Uploading a new API description to ReadMe +#### Uploading a New API Definition to ReadMe This will upload `path-to-openapi.json` to your project and return an ID and URL for you to later update your file, and view it in the client. ```sh rdme openapi [path-to-file.json] ``` -#### Editing (resync) an existing API description -This will edit (resync) an existing API description (identified by `--id`) within your ReadMe project. +#### Editing (Re-Syncing) an Existing API Definition +This will edit (re-sync) an existing API definition (identified by `--id`) within your ReadMe project. ```sh rdme openapi [path-to-file.json] --id={existing-id} ``` -#### Uploading or editing an API description in a project version +#### Uploading or Editing an API Definition in a Project Version You can additional include a version flag, specifying the target version for your file's destination ```sh @@ -69,7 +69,7 @@ rdme openapi [path-to-file.json] --version={project-version} rdme openapi [path-to-file.json] --id={existing-id} --version={project-version} ``` -#### Omitting the file path +#### Omitting the File Path If you run `rdme` within a directory that contains your Swagger or OpenAPI definition, you can omit the file path. We will then look for a file with the following names, and upload that: `swagger.json`, `swagger.yaml`, `openapi.json`, and `openapi.yaml` ```sh @@ -77,37 +77,37 @@ rdme openapi ``` ### Docs -#### Syncing a folder of Markdown docs to ReadMe +#### Syncing a Folder of Markdown Docs to ReadMe ```sh rdme docs path-to-markdown-files --version={project-version} ``` -#### Edit a single ReadMe doc on your local machine +#### Edit a Single ReadMe Doc on Your Local Machine ```sh rdme docs:edit --version={project-version} ``` ### Versions -#### Get all versions associated with your project +#### Get All Versions Associated With Your Project ```sh rdme versions ``` If you wish to see the raw output from our API in this response, supply the `--raw` flag. -#### Get all information about a particular version +#### Get All Information About a Particular Version ```sh rdme versions --version={project-version} ``` If you wish to see the raw output from our API in this response, supply the `--raw` flag. -#### Create a new version +#### Create a New Version ```sh rdme versions:create | --version={project-version} ``` -##### Automating this process +##### Create a New Version If you wish to automate the process of creating a new project version, and not have the CLI prompt you for input, you can do so by supplying the necessary flags to `versions:create`. For example: @@ -118,21 +118,21 @@ rdme versions:create | --version={project-version} --fork={version-for See `rdme versions:create --help` for a full list of flags. -#### Update a version +#### Update a Version ```sh rdme versions:update --version={project-version} ``` Like `versions:create`, if you wish to automate this process and not be blocked by CLI input, you can supply the necessary flags to this command. See `rdme versions:update --help` or [automating this process](#automating-this-process) for more information. -#### Delete a version +#### Delete a Version You can remove a specific version from your project, as well as all of the attached specs ```sh rdme versions:delete --version={project-version} ``` -### Open your ReadMe project in your browser +### Open Your ReadMe Project in Your Browser If you are logged in, this will open the project in your browser: ```sh From db6297af1edef772db54f7f60c101961130dd089 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 25 Aug 2021 11:37:22 -0500 Subject: [PATCH 2/4] docs: make language OpenAPI forward, deprecate `rdme swagger` --- README.md | 10 +++++----- __tests__/cmds/openapi.test.js | 10 +++++----- src/cmds/openapi.js | 12 ++++++------ src/cmds/swagger.js | 3 ++- 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index da31e4a65..28e2629b7 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) -`rdme` is the CLI wrapper for [ReadMe's RESTful API](https://docs.readme.com/developers/reference/intro). It allows you to upload and edit [Swagger](https://swagger.io/) and [OAS](https://swagger.io/specification/) files associated with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. +`rdme` is the CLI wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to upload and edit [OpenAPI](https://swagger.io/specification/) and [Swagger](https://swagger.io/specification/v2/) files associated with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. * [Configuration](#installation) * [Installation](#installation) @@ -39,10 +39,10 @@ If you wish to get more information about any command within `rdme`, you can exe * `--key `: The API key associated with your ReadMe project. You can obtain this from your dashboard, or alternatively if you log in with `rdme login`, we will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`), saving you the hassle of having to supply this argument on commands that have it. * `--version `: Your project version. -### Swagger / OpenAPI -ReadMe supports both [Swagger 2.0](https://swagger.io/docs/specification/2-0/basic-structure/) and [OpenAPI 3.0](https://swagger.io/docs/specification/about/). +### OpenAPI / Swagger +ReadMe supports both [OpenAPI 3.0.x](https://swagger.io/specification/) and [Swagger 2.x](https://swagger.io/specification/v2/). -> ℹ️ Note that the `rdme swagger` command is also available alongside `rdme openapi` also supports both OpenAPI and Swagger API definitions. +> ℹ️ 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 This will upload `path-to-openapi.json` to your project and return an ID and URL for you to later update your file, and view it in the client. @@ -70,7 +70,7 @@ rdme openapi [path-to-file.json] --id={existing-id} --version={project-version} ``` #### Omitting the File Path -If you run `rdme` within a directory that contains your Swagger or OpenAPI definition, you can omit the file path. We will then look for a file with the following names, and upload that: `swagger.json`, `swagger.yaml`, `openapi.json`, and `openapi.yaml` +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 openapi diff --git a/__tests__/cmds/openapi.test.js b/__tests__/cmds/openapi.test.js index a96464661..e394a2854 100644 --- a/__tests__/cmds/openapi.test.js +++ b/__tests__/cmds/openapi.test.js @@ -61,7 +61,7 @@ describe('rdme openapi', () => { expect(output).toMatch(/we found swagger.json/i); expect(output).toMatch(/successfully uploaded/); expect(output).toMatch(exampleRefLocation); - expect(output).toMatch(/to update your swagger or openapi file/i); + expect(output).toMatch(/to update your openapi or swagger file/i); fs.unlinkSync('./swagger.json'); return mock.done(); @@ -116,7 +116,7 @@ describe('rdme openapi', () => { expect(output).not.toMatch(/we found swagger.json/i); expect(output).toMatch(/successfully uploaded/); expect(output).toMatch(exampleRefLocation); - expect(output).toMatch(/to update your swagger or openapi file/i); + expect(output).toMatch(/to update your openapi or swagger file/i); mock.done(); }); @@ -236,7 +236,7 @@ describe('rdme openapi', () => { const output = getCommandOutput(); expect(output).toMatch(/successfully uploaded/); expect(output).toMatch(exampleRefLocation); - expect(output).toMatch(/to update your swagger or openapi file/i); + expect(output).toMatch(/to update your openapi or swagger file/i); mock.done(); }); @@ -254,7 +254,7 @@ describe('rdme openapi', () => { .basicAuth({ user: key }) .reply(200, { version: '1.0.0' }); - await expect(openapi.run({ key, version })).rejects.toThrow(/We couldn't find a Swagger or OpenAPI file./); + await expect(openapi.run({ key, version })).rejects.toThrow(/We couldn't find an OpenAPI or Swagger file./); mock.done(); }); @@ -273,7 +273,7 @@ describe('rdme swagger', () => { const id = '5aa0409b7cf527a93bfb44df'; await expect(swagger.run({ spec: '', key, id, version })).rejects.toThrow( - "We couldn't find a Swagger or OpenAPI file.\n\n" + + "We couldn't find an OpenAPI or Swagger file.\n\n" + 'Run `rdme openapi ./path/to/file` to upload an existing file or `rdme oas init` to create a fresh one!' ); }); diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index 1985c9f23..2f708ed4e 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -12,7 +12,7 @@ const parse = require('parse-link-header'); exports.command = 'openapi'; exports.usage = 'openapi [file] [options]'; -exports.description = 'Upload, or sync, your Swagger/OpenAPI file to ReadMe.'; +exports.description = 'Upload, or sync, your OpenAPI/Swagger file to ReadMe.'; exports.category = 'apis'; exports.position = 1; @@ -64,12 +64,12 @@ exports.run = async function (opts) { const encodedString = Buffer.from(`${key}:`).toString('base64'); async function callApi(specPath, versionCleaned) { - // @todo Tailor messaging to what is actually being handled here. If the user is uploading an OpenAPI file, never mention that they uploaded/updated a Swagger file. + // @todo Tailor messaging to what is actually being handled here. If the user is uploading a Swagger file, never mention that they uploaded/updated an OpenAPI file. async function success(data) { const message = !isUpdate - ? "You've successfully uploaded a new Swagger file to your ReadMe project!" - : "You've successfully updated a Swagger file on your ReadMe project!"; + ? "You've successfully uploaded a new OpenAPI file to your ReadMe project!" + : "You've successfully updated a OpenAPI file on your ReadMe project!"; const body = await data.json(); @@ -79,7 +79,7 @@ exports.run = async function (opts) { '', `\t${`${data.headers.get('location')}`.green}`, '', - 'To update your Swagger or OpenAPI file, run the following:', + 'To update your OpenAPI or Swagger file, run the following:', '', // eslint-disable-next-line no-underscore-dangle `\trdme openapi FILE --key=${key} --id=${body._id}`.green, @@ -215,7 +215,7 @@ exports.run = async function (opts) { reject( new Error( - "We couldn't find a Swagger or OpenAPI file.\n\n" + + "We couldn't find an OpenAPI or Swagger file.\n\n" + 'Run `rdme openapi ./path/to/file` to upload an existing file or `rdme oas init` to create a fresh one!' ) ); diff --git a/src/cmds/swagger.js b/src/cmds/swagger.js index 0db96fd38..0e9fd4bbb 100644 --- a/src/cmds/swagger.js +++ b/src/cmds/swagger.js @@ -3,7 +3,7 @@ const openapi = require('./openapi'); exports.command = 'swagger'; exports.usage = 'swagger [file] [options]'; -exports.description = 'Alias for `rdme openapi`.'; +exports.description = 'Alias for `rdme openapi` [deprecated].'; exports.category = 'apis'; exports.position = 2; @@ -37,5 +37,6 @@ exports.args = [ ]; exports.run = async function (opts) { + console.warn('`rdme swagger` has been deprecated. Please use `rdme openapi` instead.'); return openapi.run(opts); }; From 075774d90ca36291714f6a02f6b1eed045817f16 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 25 Aug 2021 11:39:56 -0500 Subject: [PATCH 3/4] docs: update npm tags --- package.json | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 088b1322d..cb2e2fe2f 100644 --- a/package.json +++ b/package.json @@ -13,9 +13,12 @@ "tags": [ "api", "apis", + "openapi", "swagger", - "open api initiative", - "open api spec", + "openapi initiative", + "openapi specification", + "openapi spec", + "openapi document", "oai", "oas", "apidoc", From 4dcd1189518d639ee40dcf0838cdcd60c32226ce Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 25 Aug 2021 11:44:59 -0500 Subject: [PATCH 4/4] docs: grammatical fix --- src/cmds/openapi.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index 2f708ed4e..27f68070f 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -69,7 +69,7 @@ exports.run = async function (opts) { async function success(data) { const message = !isUpdate ? "You've successfully uploaded a new OpenAPI file to your ReadMe project!" - : "You've successfully updated a OpenAPI file on your ReadMe project!"; + : "You've successfully updated an OpenAPI file on your ReadMe project!"; const body = await data.json();