docs: update language to be more OpenAPI forward (#359)

* docs: title-case headings

* docs: make language OpenAPI forward, deprecate `rdme swagger`

* docs: update npm tags

* docs: grammatical fix

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)
@@ -35,30 +35,30 @@ rdme login
 ## Usage
 If you wish to get more information about any command within `rdme`, you can execute `rdme help <command>` or `rdme <command> --help`. You an also execute `rdme help` to see a global list of commands that `rdme` offers.
 
-### Common `rdme` options
+### Common `rdme` Options
 * `--key <string>`: 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 <string>`: 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 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,45 +69,45 @@ 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
-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`
+#### 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 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 <slug> --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> | --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> | --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

__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!'
     );
   });

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",

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 an 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!'
       )
     );

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);
 };