Quickstart Guide
This quickstart guide will help you get started with creating your first project, uploading an OpenAPI Specification (OAS) file, and writing your first guide.
Overview
With our powerful documentation platform, you can effortlessly create, manage, and publish API documentation and guides. We provide various options for docs within your hub, including an API Reference, Guides, Recipes, Changelog, Discussions, and a Landing Page. This guide will walk you through the steps to help you kickstart your docs!
Step 1: Creating Your Project
Creating a project is the first step towards building comprehensive and user-friendly documentation. This process involves setting up your project with a name, subdomain, and logo that match your brand's identity. Follow the steps below to get started:
1. Sign Up/Log In
Go to ReadMe and sign up for an account if you haven't already. If you have an account, log in.
2. Create a New Project
-
Once logged in, click on the + New Project button on your dashboard.
-
Enter a Project Name and subdomain.
-
Optional: Click Upload Image to upload a logo for your project. Alternatively, you can click Use our logo to get started with a ReadMe logo if you don't have one - you can always add a logo later!
-
Click Create to proceed to your project.
Nice work! Now that you've created your project, you'll land on our Quickstart page in your Project Dashboard. Let's get started with uploading your first OpenAPI Specification (OAS) file.
Step 2: Uploading Your First OAS File
Your API Reference not only helps users understand your API, but with ReadMe, it’s where they can try out your API in real time. The API Reference is where you'll list all your endpoints and parameters. Follow the steps below to import your OAS file:
1. Navigate to API Reference
In your Project Dashboard, go to the API Reference section.
2. Upload OAS File
-
Click on the Add your first API button.
-
Click the API Import button.
-
You have the option to upload your OAS file using the command line, GitHub repo, file, or URL. For the purpose of this guide we're going to upload the API via file.
-
Click file and choose your OpenAPI Specification (OAS) file (JSON or YAML format) from your computer.
-
Upon successful sync, you'll see a Next Steps modal. You can dismiss this for now.
3 View your API Reference
After uploading your OAS file, you can click the preview icon next to the Save button to view your APIs.
4. Save and Publish
-
Save your settings and publish the API documentation.
-
Your API endpoints, parameters, and responses will be automatically generated based on the OAS file.
Step 3: Creating a Guide via the Editor
In this section, we'll walk you through creating a guide directly from the ReadMe dashboard using the Markdown editor. While this is the most straightforward method, you can also create guides via the API or the CLI.
1. Click "New Category"
-
In your Project Dashboard, navigate to the Guides section.
-
Click on the New Category button.
2. Enter a "New Category" Name
Enter a name for your new category. Let's name it "Getting Started."
3. Add a New Page
Click the "+" button next to your new category to add a new page.
4. Enter a Title for Your New Guide
Enter a title for your guide, such as "Introduction."
5. Write Your Guide
Use the editor to write your guide. You can add headings, text, code snippets, images, and more. Utilize Markdown for formatting your content.
6. Save Your Guide
-
Once you've finished writing your guide, click Save.
-
You can preview your guide using the preview icon to ensure everything looks good on the front-end.
Updated about 2 months ago
Congratulations! You've successfully created your first ReadMe project, uploaded your first OAS file, and written your first guide. Explore more features to enhance your documentation, such as adding recipes, creating a changelog, and setting up a landing page.