[📑 Docs]: NEW tutorial, "How to create documentation with AsyncAPI"

[quetzalliwrites]

What Dev Docs changes are you proposing?

Write NEW tutorial: "How to create documentation with AsyncAPI."

---

NEW agnostic tutorials outline template

Introduction

In this AsyncAPI tutorial, we're going to learn how to create documentation with AsyncAPI.

Background context

(add info on technologies used and why it matters)

Installation guide

Before you proceed to the next stage, you'll need to download a few things:

• Install Node.js (v15 or newer).
• Install Git on your Operating System (OS):
  • Install Git on MacOs
  • Install Git on Windows
  • Install Git on Linux

Tutorial step 1

In this step, we will...

Tutorial step 2

In this step, we will...

Tutorial step 3

In this step, we will...

Summary:

In this tutorial, we built...

Next steps:

Now that you've completed this tutorial, why don't you check out how to do ABC with our ABC tutorial? You may also want to check out the XYZ tutorial to learn how to XYZ.

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[quetzalliwrites]

All right, @starlightknown! It's time for a new challenge... writing a new tutorial from scratch! ✨✨✨

I would research and ask questions first with Lukasz, but you can also leave a question in our slack #2_general channel to get advice from more people in the community. Let us know how we can help you!

[starlightknown]

https://www.asyncapi.com/docs/tools#code-first-tools would that be a tutorial using any one of these tools? or it's this https://www.asyncapi.com/tools/generator and generate docs using generator tool @alequetzalli

[quetzalliwrites]

(we agreed that we'd wait for an article from Lukasz on this topic to go live before Karuna write this tutorial 😀 )

[quetzalliwrites]

Heyooo @Annysah, we're actually going change the direction of this tutorial and assign this one to you; you may remember this change is because of what we're talking about in Slack:

We're going to update the Streetlights tutorial by converting it into 4 separate NEW tutorials:

• create AsyncAPI document
• validate AsyncAPI document
• generate code
• validate code messages/events

From the above list, I am going to assign you @Annysah the following tutorials instead:

• create AsyncAPI document
• generate code

We already have the content for those two mini tutorials from our current Streetlights tutorial so it should be easy for your to flesh out the rest of these new docs. :)

cc @starlightknown

[Annysah]

Thanks @alequetzalli!

to be double sure, the scenario in this case will be the "Streetlights" right?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[ro4i7]

hello @alequetzalli

Is this issue still open, if it is please assign it to me? and give feedback on my below solution:

I have written step-by-step tutorial on "How to create documentation with AsyncAPI". Here is a proposed outline:

Introduction

In this tutorial, we will learn how to create documentation with AsyncAPI. AsyncAPI is an open-source specification for asynchronous APIs that allows you to define and document your message-driven APIs in a machine-readable format. With AsyncAPI, you can generate documentation, code, and tests automatically. This tutorial assumes that you have a basic understanding of APIs and messaging.

Background context

Before we begin, let's review the technologies we will be using in this tutorial:

• AsyncAPI: The open-source specification for asynchronous APIs that we will use to define and document our API.

• Node.js: The JavaScript runtime environment we will use to install and run the AsyncAPI generator.

• Git: The distributed version control system we will use to manage our project and documentation.

Prerequisites

Before we get started, you need to have the following software installed on your computer:

• Node.js (version 15 or newer): You can download the latest version of Node.js from the official website: https://nodejs.org/.

• Git: You can download Git for your operating system from the following links:

1. Install Git on MacOs: https://git-scm.com/download/mac

2. Install Git on Windows: https://git-scm.com/download/win

3. Install Git on Linux: https://git-scm.com/download/linux

Tutorial step 1: Setting up a new AsyncAPI project

In this step, we will create a new AsyncAPI project and install the necessary dependencies.

1. Create a new directory for your project:

mkdir my-asyncapi-project
cd my-asyncapi-project

2. Initialize a new Node.js project:

npm init -y

3. Install the AsyncAPI generator:

npm install @asyncapi/generator --save-dev

Tutorial step 2: Defining an AsyncAPI specification

In this step, we will define an AsyncAPI specification that describes our API.

1. Create a new file named asyncapi.yml in the root directory of your project.

2. Add the following content to the asyncapi.yml file:

asyncapi: '2.0.0'
info:
  title: My AsyncAPI Tutorial
  version: '1.0.0'
channels:
  user/signedup:
    publish:
      message:
        payload:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string

3. Save the asyncapi.yml file.

Tutorial step 3: Generating documentation

In this step, we will generate documentation from our AsyncAPI specification.

1. Create a new file named generate.js in the root directory of your project.

2. Add the following content to the generate.js file:

const { Generator } = require('@asyncapi/generator');

const generator = new Generator('@asyncapi/html-template', {
  asyncapi: '2.0.0',
  templateParams: {
    sidebarOrganization: 'byTags'
  }
});

generator.generateFromFile('asyncapi.yml')
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

3. Save the generate.js file.
4. Run the following command in your terminal to generate the documentation:

node generate.js

5. The generated documentation will be saved in a new directory named `./docs in your project's root directory. You can open the index.html file in the docs directory to view the documentation in your browser.

6. You can customize the output of the documentation generator by changing the parameters passed to the Generator constructor. For example, you can use a different template by changing the first parameter to the Generator constructor to the name of the template you want to use.

Summary

In this tutorial, we learned how to generate documentation using the AsyncAPI Generator. With this tool, we can quickly and easily generate high-quality documentation for our APIs.

[starlightknown]

Hey @ro4i7 thanks for putting it here but as you can see this issue is closed, it's already been done and is live on website. Please check if the issues are open before starting to work on it next time, we don't want your hard work to go waste

[quetzalliwrites]

@ro4i7 Please stop spamming issues, you cannot keep adding content blocks like this in comment threads. Please follow outlined processes for submitting contributions:

1. Leave a comment in issue to state interest in doing that work or open new issue with your contribution idea.
2. open a PR for approved task
3. re-write as needed, based on the reviews rounds you undergo in your PR from the code owners automatically added to PRs
4. all goes well, eventually your PR gets approved by all and we merge ✨