Update create-openapi-repo README (#64)

* README updates * README updates * README updates * Add TOC * Adds intro text * Remove TOC, update intro * Remove duplicate text from intro * Intro text updates * README updates * Update examples link text * Final README updates * Apply suggestions from code review --------- Co-authored-by: drichards-87 <[email protected]> Co-authored-by: Heather Cloward <[email protected]>
Redocly · Apr 5, 2024 · 161759a · 161759a
1 parent ff847f0
commit 161759a
Showing 1 changed file with 90 additions and 100 deletions.
diff --git a/README.md b/README.md
@@ -1,141 +1,131 @@
 # create-openapi-repo
 
-[![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url]
-
-> Generate an organized multi-file OpenAPI repository.
+A tool for generating multi-file OpenAPI definitions.
 
-<center>
+[![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url]
 
+<p align="center">
 <img src="./logo.png" width="500px"/>
+</p>
 
-</center>
-
-## Who?
-You! Hello.  Do you need to write or contribute to an OpenAPI definition?  If so, read on...
-
-## What?
-We recommend a docs-like-code approach to OpenAPI definitions:
-- Write it using your favorite text-editor or IDE (we love VSCode).
-- Organize it into multiple files and folders to make it easy to navigate.
-- Store it using source control (such as GitHub).
-- Continuously validate it using our free [openapi-cli tool](https://github.com/redocly/openapi-cli) or our free continuous validation service (coming soon).
-- Bundle it (for a smaller footprint to use in other tools or for tools that do not support a multi-file format).
-
-## Why?
-There are a few advantages in hosting your API definition on GitHub:
- - Community engagement (PR's and issues -- if you have a public repo)
- - Advertisment in the GitHub community
- - Hosting on GitHub pages (perfect uptime, CDN, Jekyll, custom domains with CNAME)
- - Revision history, branching, CI
- - Review and approval workflows using Pull Requests
- - Fast on-boarding time (developers and tech writers know how to use GitHub :smile:)
- - Fully compatible with Redocly API Reference too
-
- There are also some advantages to a multi-file YAML format OpenAPI definition:
- - Reuse schema objects to keep things DRY (don't repeat yourself) 
- - Smaller diffs compared to JSON (especially for markdown descriptions)
- - Easier to navigate
- - Easier to edit with confidence
+Need to write or contribute to an OpenAPI definition? `create-openapi-repo` can help with that!
 
 ## Features
-This generator helps to create a GitHub repo with the following features:
- - Split a big (or small) OpenAPI definition into smaller files organized into folders
- - Bundle it into a single file for deployment
- - Continuous integration/deployment on Travis or Redocly Workflows
- - Code samples as separate files
- - Automate deployment of your OpenAPI definition and docs
- - OpenAPI definition is validated after each commit
+
+ - OpenAPI 3.0 support
+ - Split an existing OpenAPI definition into multiple files
+ - Bundle a multi-file definition into a single file
+ - Validate your OpenAPI definition using our free [openapi-cli tool](https://github.com/redocly/openapi-cli)
+ - Automate deployment of your API reference docs using CI/CD workflows
+ - Maintain code samples as separate files
  - Live editing in your editor of choice :heart_eyes:
 
-## Structure
+## Examples
+- [Rebilly](https://github.com/Rebilly/RebillyAPI)
+- [Thingful](https://github.com/thingful/openapi-spec)
 
-You will have a structure similar to this:
-```
-    ├── .redocly.yaml
-    ├── LICENSE
-    ├── README.md
-    ├── docs
-    │   ├── favicon.png
-    │   └── index.html
-    ├── openapi
-    │   ├── README.md
-    │   ├── code_samples
-    │   │   ├── C#
-    │   │   │   └── echo
-    │   │   │       └── post.cs
-    │   │   ├── PHP
-    │   │   │   └── echo
-    │   │   │       └── post.php
-    │   │   └── README.md
-    │   ├── components
-    │   │   └── README.md
-    │   └── paths
-    │       └── README.md
-    └── package.json
-```
-
-However, you can adjust it to any structure you prefer.
+## Prerequisites
 
-The `openapi` folder is where your OpenAPI definition will live.  Inside there, and the sub-folders, there are `README.md` files to help guide you further. This is also where your entrypoint `openapi.yaml` will live.
+Before you begin, make sure you have the following prerequisites:
 
-The `components` folder is where you will organize sub-folders such as `schema` to define your schema.
+ - [Node.js](https://nodejs.org/)
+ - [Github repository](https://help.github.com/articles/create-a-repo/#create-a-new-repository-on-github) (new OpenAPI definitions only)
 
-The `paths` folder is where you will organize your paths. There will be a 'README.md' file in there with suggestions for how to organize it into specially named files (or folders) that use an `@` in place of a `/` (because files cannot have a `/` character in them).  You will also be able to use path parameters by wrapping them in curly braces `{example}`.
+## Installation
 
-The `.redocly.yaml` file is a universal configuration for various Redocly tools including the lint tool and reference doc engine.
+1. Navigate to the location where you want to create the repository.
+2. Run one of the following commands:
+   - Install `create-openapi-repo` globally:
 
-## Commands
+        ```bash
+        npm install -g create-openapi-repo
+        ```
 
-The generated repository includes installing a dependency for our `openapi-cli` tool which supports commands such as `validate`, `bundle`, and more.  There are scripted shortcuts defined in the repository's `package.json`.  
+   - Install `create-openapi-repo` using [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b):
 
+        ```bash
+        npx create-openapi-repo
+        ```
 
-## Examples of generated repositories
-- https://github.com/Rebilly/RebillyAPI
-- https://github.com/thingful/openapi-spec
-- https://github.com/TwineHealth/TwineDeveloperDocs
+3. Follow the [interactive prompts](https://github.com/Redocly/create-openapi-repo#usage) to complete the installation.
 
-## How to generate your repository
+### Upgrading from a prior version
 
-We assume you already have [node.js](https://nodejs.org/) installed.
+To upgrade from a prior version of `create-openapi-repo`, run the following command in the root folder of your repository:
 
-- Install `create-openapi-repo` globally:
 ```bash
-npm install -g create-openapi-repo
+npx create-openapi-repo --migrate-2-3
 ```
-or use [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b):
 
-We'll use `npx` in this example.  However, remove `npx` if you installed it globally.
+**Note:** Plugins aren't included in the migration. You'll need to manually add them to the `transformers` folder.
 
-```bash
-npx create-openapi-repo
-```
+## Usage
 
-You will be presented with some questions. You can create a new definition or use an existing definition to initialize your project.
+`create-openapi-repo` provides interactive prompts to help guide you through the installation process. Two basic workflows are supported:
 
-Please note, if you do start a new one, remember to [create a GitHub repo](https://help.github.com/articles/create-a-repo/#create-a-new-repository-on-github) where your OpenAPI definition will live.
+### Split an existing OpenAPI definition
 
-If you use the prior version of this generated repository, please read the following upgrade instructions.
+The interactive prompts allow you to specify the path to the file on your local machine, as well as rename the API (optional). After you choose to proceed, `create-openapi-repo` initializes the repository and splits your OpenAPI definition into multiple files.
 
-#### Upgrading from a prior version
+### Create a new OpenAPI definition
 
-Migrate your repository from a previous structure of OpenAPI repo to this newer structure with our migration tool. 
+The interactive prompts allow you to specify a name for the API and choose whether to create a sub-folder for code sample files. After you choose to proceed, `create-openapi-repo` initializes the repository and populates it with placeholder files and folders. 
 
-Run this in the root folder of your repo.
+## Directory structure
 
-```bash
-npx create-openapi-repo --migrate-2-3
+The directory structure will look similar to this:
+
+**Note:** You can modify the directory structure to meet your specific requirements.
+
+```
+    ├── .redocly.yaml
+    ├── LICENSE
+    ├── README.md
+    ├── docs
+    │   ├── favicon.png
+    │   └── index.html
+    ├── openapi
+    │   ├── README.md
+    │   ├── code_samples
+    │   │   ├── C#
+    │   │   │   └── echo
+    │   │   │       └── post.cs
+    │   │   ├── PHP
+    │   │   │   └── echo
+    │   │   │       └── post.php
+    │   │   └── README.md
+    │   ├── components
+    │   │   └── README.md
+    │   └── paths
+    │       └── README.md
+    └── package.json
 ```
 
-Note: the migration tool does not migrate plugins automatically. You would need to manually add them to the `transformers` folder. 
+ - `.redocly.yaml`: Configuration file for defining settings for various Redocly tools, including the lint tool and reference docs engine.
+ - `openapi`: Top-level folder that contains your OpenAPI definition, `openapi.yaml` entrypoint file, and sub-folders for `paths`, `components`, and `code_samples`.
+ - `code_samples`: Folder for organizing code samples into sub-folders, such as C# and PHP.
+ - `components`: Folder for organizing reusable components into sub-folders, such as `schema` and `response` objects.
+ - `paths`: Folder for organizing path definitions. Each path should be referenced from the `openapi.yaml` entrypoint file.
+
+## Commands
+
+The generated repository installs a dependency for our `redocly-cli` tool which supports the following commands:
+
+ - `npm start`: Starts the preview server
+ - `npm run build`: Bundles a multi-file OpenAPI definition into a single file
+ - `npm test`: Validates the OpenAPI definition
+
+**Note:** Additional scripted shortcuts are defined in the repository's `package.json` file.
 
-## Support
+## Contribute
 
-Thank you for wanting to support us. Here are some ideas how to support us:
+Interested in contributing to this project? Here are some ways you can support us:
 
-* Star us
-* Tell a friend or colleague about us (or Tweet about us)
-* Write an article about it (and let us know) -- open an issue to let us know, with the link.
-* Consider our commercial products if are looking for automation to ease the docs-like code workflow, hosting along with conveniences like custom domains, access controls and previews, API reference documentation, or a full developer portal:  https://redoc.ly
+ - Submit a pull request.
+ - Star us on Github.
+ - Tell a friend or colleague about us (or Tweet about us).
+ - Write an article or blog post. Let us know by opening an issue with a link to the article.
+ - Looking to build a modern documentation workflow? Our [commercial products](https://redoc.ly) can help you maintain and deploy API reference docs and developer portals.
 
 [npm-image]: https://badge.fury.io/js/generator-openapi-repo.svg
 [npm-url]: https://npmjs.org/package/generator-openapi-repo