diff --git a/README.md b/README.md index 69905cfd898..9a64ced7fbb 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,6 @@ Use the following tools to set up the project: - [Node.js](https://nodejs.org/) v16.0.0+ - [npm](https://www.npmjs.com/) v7.10.0+ - ## Run locally 1. Fork the repository by clicking on `Fork` option on top right of the main repository. diff --git a/pages/docs/concepts/application.md b/pages/docs/concepts/application.md index 6de5af6d829..1d9c4634a94 100644 --- a/pages/docs/concepts/application.md +++ b/pages/docs/concepts/application.md @@ -21,7 +21,3 @@ flowchart TD D --> F[CONSUMER application] ``` The above diagram describes a message communication traveling through a channel between a **PRODUCER application** and a **CONSUMER application**. - - -When writing your AsyncAPI document, make sure to describe what a user can do with your application; not what the application does. In other words, if your application is a producer, your AsyncAPI document should describe where users can subscribe to, to receive messages produced by your producer application. - diff --git a/pages/docs/guides/message-validation.md b/pages/docs/guides/message-validation.md deleted file mode 100644 index c8eca99dc97..00000000000 --- a/pages/docs/guides/message-validation.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Message validation -description: This guide explains different use cases for AsyncAPI message validation. -weight: 130 ---- - -## Introduction -This guide explains different concepts of validating AsyncAPI messages. You will also learn what role AsyncAPI documents play in validation. - -## Message validation -To understand AsyncAPI message validation, we must first understand the basic components involved. -- Producer: responsible for producing messages. -- Consumer: responsible for getting the producer's messages. -- Broker: acts as a bridge between the consumer and the producer because messages travel through the broker. - -Message validation can occur in different places in your system. This guide highlights three of those: -- Both producers and consumers can do validation internally during runtime. -- API Gateway can handle message validation. -- Validation of messages can be a native solution implemented by the Schema Registry. -Because consumers and producers cannot communicate directly, the AsyncAPI file dictates what should be included in the payload when a service produces a message. The AsyncAPI document also tells the consumer about the message's properties. -Let's further break down how validation works for all. - -### Runtime validation -Messages produced and consumed are both required for runtime message validation. The AsyncAPI document should include descriptions of payload schemas so that you can read them in your application and validate messages that are consumed and produced by the application. - -Before messages reach the consumer, runtime validation ensures that any errors are resolved and valid messages are sent to your application. - -An example implementation of message validation in runtime is the [asyncapi-validator](https://github.com/WaleedAshraf/asyncapi-validator) library that enables you to validate messages produced/consumed in your application against schemas provided in your AsyncAPI document. -Check out the [message validation in the runtime](https://www.asyncapi.com/docs/tutorials/message-validation) tutorial if you want to get your hands dirty with message validation. - -```mermaid -graph TD - subgraph Producer - G[Message produced] -->|Message| B{Is Message valid?} - B -->|No| A[Logs] - end - B -->|Yes| C[Broker] - C -->|Message| E{Is Message valid?} - subgraph Consumer - E -->|No| F[Logs] - E -->|Yes| H[Message consumed] - end -``` - -### Gateway validation -A gateway intercepts all incoming messages and routes them through the middleware and handler pipelines. The gateway sits between the producer and the broker. First, the messages are routed through the gateway, and then the gateway determines whether the message is valid. If the message is invalid, it displays an error and is not forwarded to the broker. - -An example implementation of message validation in a gateway is the [AsyncAPI gateway](https://github.com/asyncapi/event-gateway). It intercepts all incoming messages moving them into a pipeline of middlewares and handlers such as message validation. You can use a Kafka consumer/producer[(kcat)](https://github.com/edenhill/kcat), a broker, and a simple WebSocket to run the AsyncAPI gateway in your machine. -Check out an [AsyncAPI file demo with Studio](https://studio.asyncapi.com/?url=https://raw.githubusercontent.com/asyncapi/event-gateway/master/deployments/k8s/event-gateway-demo/event-gateway-demo.asyncapi.yaml) to learn more about how an AsyncAPI file can be used in gateway validation. - - -Currently, only the Kafka protocol is supported. - - -```mermaid -graph TD - PR[Producer]-- Message --- EG[AsyncAPI Event-Gateway] - EG -- Message --- EGV{Is Message valid?} - EGV -->|Yes| BR[Broker] - EGV --- |No| INV{Fail when invalid?} - INV -->|Yes| ERR[/Fail/] -- Produce request errored --> PR - INV -->|No| BR -``` -The AsyncAPI document is important because payload schemas are taken from it, and messages are validated against it in your application. -You can spin up the AsyncAPI gateway using an AsyncAPI file. All the messages are forwarded to a WebSocket endpoint; if the message/payload is invalid, it includes a validation error message. - -### Schema Registry validation -Producers and consumers do not communicate with each other directly; rather, information transfer happens via Kafka. At the same time, the consumer still needs to know the type of data the producer is sending. Imagine if the producer starts sending bad data to Kafka or if the data type of your data gets changed. We need a way to have a common data type that must be agreed upon. - -This is where Schema Registry comes into play. It is an application that runs outside your Kafka protocol and handles schema distribution to producers and consumers by storing a copy of the schema in its local cache and validating them in Kafka. - -```mermaid -sequenceDiagram -Producer ->> Schema Registry: Register/checks message schema -Schema Registry ->> Producer: Return registration result - -Producer ->> Kafka: Publish message -Kafka ->> Consumer: Recieves message -Consumer ->> Schema Registry: Validate message schema -Schema Registry ->> Consumer: Return validation result -``` - -With the Schema Registry in place, the producer first talks to the Schema Registry and checks if the schema of the message it wants to send is available before sending it to the broker. If it cannot locate the schema, it registers it in the Schema Registry. Then the producer sends a message to the broker prefixed with a unique schema ID. When the consumer processes this message, it will communicate with the Schema Registry using the schema ID obtained from the producer. If there is a schema mismatch, the Schema Registry will throw an error, informing the producer that it violates the schema agreement. - -AsyncAPI is not directly involved in validation based on the Schema Registry. The good thing is that you do not have to duplicate schemas in your AsyncAPI document stored in Schema Registry. You can reference schemas from Schema Registry in your AsyncAPI documents. -Here's an example of an AsyncAPI document where you can see both `schemaFormat` and `payload` referenced from the Schema Registry: -```yml -asyncapi: 2.6.0 -info: - title: Example with Avro - version: 0.1.0 -channels: - example: - publish: - message: - schemaFormat: 'application/vnd.apache.avro;version=1.9.0' - payload: - $ref: 'https://example.europe-west3.gcp.confluent.cloud/subjects/test/versions/1/schema' -``` - ---- - diff --git a/pages/docs/guides/validate.md b/pages/docs/guides/validate.md deleted file mode 100644 index 96b3505df66..00000000000 --- a/pages/docs/guides/validate.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Validate AsyncAPI documents" -description: In this guide, you'll learn multiple ways to validate AsyncAPI documents. -weight: 120 ---- - -## Introduction -This guide teaches multiple ways to validate AsyncAPI documents. - -## Validate AsyncAPI documents -Validating an AsyncAPI document can mean one of two things: -- Validation against the specification. -- Validation against the best practices or company governance rules also known as linting. - -### Validate against specification -Validating against the specification ensures that every content of the document is written in accordance with the AsyncAPI specification. Several tool options exist for validating against the specification: _AsyncAPI Studio_, _AsyncAPI CLI_, and _Parsers_. - -#### AsyncAPI Studio validation -[AsyncAPI Studio](https://studio.asyncapi.com/) provides a visual and easy way to validate your AsyncAPI documents against the specification. (It uses the [AsyncAPI JavaScript parser](https://github.com/asyncapi/parser-js) behind the scenes to perform syntax checks and validate documents.) - -Errors in your document are highlighted with a red underline, showing which lines are invalid. The `Diagnostics` section also provides feedback, allowing you to further troubleshoot with detailed error messages. When a document is invalid, it provides the following error: `Empty or invalid document please fix errors / define AsyncAPI document`. - -#### AsyncAPI CLI validation -The following [AsyncAPI CLI](https://github.com/asyncapi/cli#installation) command validates AsyncAPI documents in your local computer or in CI/CD automation: - - ``` - asyncapi validate asyncapi.yaml - ``` - - - -You can also open AsyncAPI Studio from the CLI by running the command `asyncapi start studio`. - - - -#### Parsers (code) validation -AsyncAPI provides official [JavaScript](https://github.com/asyncapi/parser-js) and [Go](https://github.com/asyncapi/parser-go) parsers for validating AsyncAPI documents. - - -Official parsers use JSON Schema created for AsyncAPI specification. JSON Schema is not enough to fully validate AsyncAPI documents. Learn more about custom JSON Schemas validation needs. Official JavaScript parser supports and validates these special needs. - -Take it into account if you're thinking about writing your own parser using official JSON Schema. - - -### Validation against best practices or company governance rules -Now let's discuss options for validating against best practices or company governance rules, also known as **linting**. When various teams use AsyncAPI, you want to ensure they follow the same rules and are consistent across the organization. It is not enough to validate AsyncAPI documents against official specification rules. - - - -Let's discuss an example. While the `summary` property is optional in an AsyncAPI document, you could choose to require it for your organization. You would then implement a solution that enables you to enforce internal rules on AsyncAPI documents' providers. - - - -One way this can be done is by using **Spectral**, an API linting tool which has a built-in [custom ruleset properties](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-custom-rulesets) with [AsyncAPI rules](https://meta.stoplight.io/docs/spectral/1e63ffd0220f3-async-api-rules) for the AsyncAPI specification. It also enables you to define company-specific rules that you can use internally. - -To get started: -1. Install [Spectral](https://meta.stoplight.io/docs/spectral/b8391e051b7d8-installation). -2. Create a file named `.spectral.yaml` to begin writing your API description and document rules. - Example: - ```js - { - "formats": ["asyncapi2"], - "extends": "spectral:asyncapi", - "rules": { - // add your own rules here - } - } - ``` - -3. Create and add your own custom ruleset: - ```js - { - "formats": ["asyncapi2"], - "extends": "spectral:asyncapi", - "rules": { - // add your own rules here - "valid-document-version": { - "message": "Version must match 2.x.x", - "severity": "hint", - "given": "$.info", - "then": [ - { - "field": "version", - "function": "defined" - }, - { - "field": "version", - "function": "pattern", - "functionOptions": { - "match": "^[0-9]+$" - } - } - ] - } - } - } - ``` - -4. After setting up Spectral and creating custom rules following steps 1 - 3, validate your AsyncAPI document using this Spectral CLI command: - - ``` - spectral lint asyncapi.yaml - ``` - ---- - -## Additional resources -- [AsyncAPI **Studio READme**](https://github.com/asyncapi/studio#readme) -- [AsyncAPI **CLI READme**](https://github.com/asyncapi/cli#readme) -- [AsyncAPI **JavaScript Parsers READme**](https://github.com/asyncapi/parser-js#readme) -- [AsyncAPI **Go Parsers READme**](https://github.com/asyncapi/parser-go#readme) diff --git a/pages/docs/tutorials/create-asyncapi-document.md b/pages/docs/tutorials/create-asyncapi-document.md deleted file mode 100644 index 946bb016aed..00000000000 --- a/pages/docs/tutorials/create-asyncapi-document.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Create AsyncAPI document -description: In this tutorial, you'll learn how to create an AsyncAPI document. -weight: 80 ---- - -## Introduction - -In this tutorial, you'll learn how to create an AsyncAPI document based on a sample real-world use case. Additionally, you will learn about event-driven architecture, message brokers, pub/sub pattern. - -Let's pretend you have a company called Smarty Lighting, and you install smart-city streetlight lighting systems. This smart lighting system is a use case of the Internet of Things (IoT). You will create a Smarty Lighting Streetlights API using Node.js and Mosquitto (MQTT) as the message broker. This API will allow you to manage city lights remotely. - -You want to build a system that can turn streetlights on and off based on their environmental conditions: - -- You will implement an event-driven architecture (EDA) with a message broker in its "center." - -- Streetlights will publish information about their environmental lighting to the broker. - -- Your application will connect to the broker and receive a stream of events from all the streetlights reporting their conditions. - -- Your application decides based on events when to turn the streetlight off. - -- Your application is not aware of how many streetlights are publishing events - it just connects to the broker and receives all events. - - -## Background context - -Event-driven architecture (EDA) is a design pattern built around the production, detection, and reaction to events that take place in time. In this pattern, a message broker, event publishers and subscribers are its main components for event exchange within microservices. - -[Message brokers](/docs/tutorials/getting-started/event-driven-architectures#message-broker) enables asynchronous communications between services so that the sending service need not wait for the receiving service’s reply. This allows interdependent services to “talk” with one another directly, even if they were written in different languages or implemented on different platforms. - -Furthermore, the [Pub/sub](/docs/tutorials/getting-started/event-driven-architectures#publishersubscriber) is appealing for IoT use cases due to two key features: support for flexible coupling between publishers/subscribers and inherent support for point-to-multipoint transmission. - -[MQTT](https://mqtt.org/), is a well-known protocol that is widely used in IoT applications because it was created particularly to address machine-to-machine (M2M) communication. - -## Create AsyncAPI document - -In this step, you will create an AsyncAPI document to describe the Streelights API. It will help you generate the code and the documentation later on. - -To create one, you can either use the [AsyncAPI Studio](https://studio.asyncapi.com) or the [AsyncAPI CLI](https://github.com/asyncapi/cli), depending on your project's needs.. - - - -You can create a new `asyncapi.yaml` document by running: -`asyncapi new --example=tutorial.yml --no-tty`. - - - -Go ahead to create the specification documents titled `asyncapi` with a `.yaml` extension. - - -{`asyncapi: '2.5.0' -info: - title: Streetlights API - version: '1.0.0' - description: | - The Smartylighting Streetlights API allows you - to remotely manage the city lights. - license: - name: Apache 2.0 - url: 'https://www.apache.org/licenses/LICENSE-2.0' -servers: - mosquitto: - url: mqtt://test.mosquitto.org - protocol: mqtt -channels: - light/measured: - publish: - summary: Inform about environmental lighting conditions for a particular streetlight. - operationId: onLightMeasured - message: - name: LightMeasured - payload: - type: object - properties: - id: - type: integer - minimum: 0 - description: Id of the streetlight. - lumens: - type: integer - minimum: 0 - description: Light intensity measured in lumens. - sentAt: - type: string - format: date-time - description: Date and time when the message was sent.`} - - -Let's break it down into pieces: - - -{`asyncapi: '2.5.0' -info: - title: Streetlights API - version: '1.0.0' - description: | - The Smartylighting Streetlights API allows you - to remotely manage the city lights. - license: - name: Apache 2.0 - url: 'https://www.apache.org/licenses/LICENSE-2.0'`} - - -- The `asyncapi` field indicates you use the AsyncAPI version 2.5.0. - -- The `info` field holds information about the Streetlights API. Here, the title, version, description and license were defined. - -Moving on, let's talk about the `servers` section. - -{`servers: - mosquitto: - url: mqtt://test.mosquitto.org - protocol: mqtt`} - - -In this section, you point to the Eclipse Mosquitto message broker. The `url` point to a real instance of the broker [hosted by the Mosquitto community](https://test.mosquitto.org/) and the `protocol` as MQTT. If you do not want to use the test instance, you can spin up your own broker locally with `docker run -it -p 1883:1883 eclipse-mosquitto:1.5`. But remember to change `url` to `mqtt://localhost` - -Now lets move on to the `channels` section. This section is used to describe the event names your API will be publishing and/or subscribing to. - - -{`channels: - light/measured: - publish: - summary: Inform about environmental lighting conditions for a particular streetlight. - operationId: onLightMeasured`} - - -In this example, `light/measured` is the channel name the Streetlight API will `subscribe` to (i.e, to interact with the Streetlight API you `publish` to the broker). The `operationId` property, describes what is the name of function or method that takes care of this functionality in the generated code. - -Next is the `payload` property which is used to understand how the event should look like when publishing to that channel: - - -{` payload: - type: object - properties: - id: - type: integer - minimum: 0 - description: Id of the streetlight. - lumens: - type: integer - minimum: 0 - description: Light intensity measured in lumens. - sentAt: - type: string - format: date-time - description: Date and time when the message was sent.`} - - -The `payload` property defines the content of the event using AsyncAPI schemas. It means that your event payload should contain an `id` and a `lumens` property —which are integers bigger than zero—, and a `sentAt` property that should be a string containing a date and time. - -> JSON Schema Draft 07 is 100% compatible with AsyncAPI schemas. You can also use other standards to describe payload schema, like, for example [Avro](https://github.com/asyncapi/avro-schema-parser#usage). - -## Summary - -In this tutorial, you learned how to create an AsyncAPI specification document via a real-life example with an IoT use case. - -This tutorial is just a starting point; you'll need to add your own business logic to it. Take some time to play with it. There are still lots of things to be covered, but the intent of this tutorial is to make it simple for you to get an idea of the potential. - -## Next steps -Now that you've completed this tutorial, proceed to learn how to [validate your AsyncAPI document with AsyncAPI Studio](https://www.asyncapi.com/docs/tutorials/studio-document-validation). diff --git a/pages/docs/tutorials/getting-started/asyncapi-documents.md b/pages/docs/tutorials/getting-started/asyncapi-documents.md deleted file mode 100644 index ef526918151..00000000000 --- a/pages/docs/tutorials/getting-started/asyncapi-documents.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "AsyncAPI documents" -date: 2019-04-01T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' -weight: 101 ---- - -An AsyncAPI document is a file that defines and annotates the different components of **a specific Event-Driven API**. - -The format of the file must be JSON or YAML; however, only the subset of YAML that matches the JSON capabilities is allowed. - - -{`asyncapi: 2.5.0 -info: - title: Example - version: 0.1.0 -channels: - user/signedup: - subscribe: - message: - description: An event describing that a user just signed up. - payload: - type: object - additionalProperties: false - properties: - fullName: - type: string - email: - type: string - format: email - age: - type: integer - minimum: 18`} - - -The AsyncAPI document is a machine-readable definition of your Event-Driven API. This document can be used afterward to generate documentation and code, validate the messages your application receives, and even apply API management policies to your messages before they arrive to your broker. - -Your API documentation is now machine-readable –easily parseable by code— so the myriad of useful applications is endless. diff --git a/pages/docs/tutorials/getting-started/coming-from-openapi.md b/pages/docs/tutorials/getting-started/coming-from-openapi.md deleted file mode 100644 index 78da17d7bdb..00000000000 --- a/pages/docs/tutorials/getting-started/coming-from-openapi.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "Coming from OpenAPI" -date: 2019-04-01T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' -weight: 20 ---- - -If you're coming from OpenAPI, you must know that AsyncAPI [started as an adaptation of the OpenAPI specification](https://medium.com/asyncapi/whats-new-on-asyncapi-lots-2d9019a1869d). We wanted to have as much compatibility as possible between the two so users could reuse parts in both. - -You'll find lots of similarities between OpenAPI and AsyncAPI. Just bear in mind that in the world of event-driven architectures, you have more than one protocol and therefore some things are different. Check out the following comparison chart, inspired by [Darrel Miller's blog post](https://www.openapis.org/news/blogs/2016/10/tdc-structural-improvements-explaining-30-spec-part-2): - -import OpenAPIComparison from '../../../../components/OpenAPIComparison' - - - -Aside from structural differences you must know that: - -1. AsyncAPI is compatible with OpenAPI schemas. -1. Message payload in AsyncAPI can be any value, not just an AsyncAPI/OpenAPI schema. For instance, it could be an Avro schema. -1. [AsyncAPI server object](/docs/specifications/2.2.0/#serverObject) is almost identical to its OpenAPI counterpart with the exception that `scheme` has been renamed to `protocol` and AsyncAPI introduces a new property called `protocolVersion`. -1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/specifications/2.2.0/#parameterObject) are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the [message object](/docs/specifications/2.2.0/#messageObject). Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters. - -## Conclusion - -As you have seen above, OpenAPI and AsyncAPI are very similar. In a real-world environment, systems don't have just REST APIs or events but a mix of both. Most of the time, the information flowing in the events is very similar to the one the REST APIs have to handle in requests and responses; thus, being able to reuse schemas is a huge win. - -Enough reading, it's time to get your hands dirty with some actual examples. Let's learn how to create an AsyncAPI document that defines a "Hello world" application. diff --git a/pages/docs/tutorials/getting-started/hello-world.md b/pages/docs/tutorials/getting-started/hello-world.md deleted file mode 100644 index e33a1fb2bed..00000000000 --- a/pages/docs/tutorials/getting-started/hello-world.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Hello world" -date: 2019-04-01T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' -weight: 30 ---- - -Let's define an application that's capable of receiving a "hello {name}" message. - - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -Let's get into the details of this sample specification: - - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -The first line of the specification starts with the document type `asyncapi` and the version (2.6.0). This line doesn't have to be the first one, but it's a recommended practice. - - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -The `info` object contains the minimum required information about the application. It contains the `title`, which is a memorable name for the API, and the `version`. While it's not mandatory, it's strongly recommended to change the version whenever you make changes to the API. - - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -The `channels` section of the specification houses all of the mediums where messages flow through. For example, some systems use `topic`, `event name` or `routing key`. Different kinds of information flow through each channel similar to the analogy of TV channels. - -In this example, you only have one channel called `hello`. The sample application subscribes to this channel to receive `hello {name}` messages. - - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -You can read the highlighted lines as: -> This is the `payload` of the `message` that the `Hello world application` is subscribed to. You can `publish` the `message` to the `hello` channel and the `Hello world application` will receive it. - - -{`asyncapi: 2.6.0 -info: - title: Hello world application - version: '0.1.0' -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -The `payload` object defines how the message must be structured. In this example, the message must be a string and match the given regular expression in the format `hello {name}` string. diff --git a/pages/docs/tutorials/getting-started/security.md b/pages/docs/tutorials/getting-started/security.md deleted file mode 100644 index 12effbf2ace..00000000000 --- a/pages/docs/tutorials/getting-started/security.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "Adding security" -date: 2019-04-16T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' -weight: 150 ---- - -In production environments, your API may have to access a message broker that's protected by some auth mechanisms. - -Some examples of these are: -* User & password -* Certificates -* API keys -* OAuth 2 - -If you're using AsyncAPI to define an API that connects to a message broker, you'll most probably make use of user/password or certificates. Traditionally, message brokers are infrastructure pieces that serve an internal purpose and they're not exposed to the public. That's why their security mechanisms are also simpler than what we're used to with REST APIs. However, AsyncAPI also helps you define your HTTP streaming APIs and therefore it supports more sophisticated mechanisms like OAuth2 or OpenID. - -Continuing with the `hello world` application example, let's learn how to define a simple security scheme (mechanism) for it. - - -{`asyncapi: '2.5.0' -info: - title: Hello world application - version: '0.1.0' -servers: - production: - url: broker.mycompany.com - protocol: amqp - description: This is "My Company" broker. - security: - - user-password: [] -channels: - hello: - publish: - message: - $ref: '#/components/messages/hello-msg' - goodbye: - publish: - message: - $ref: '#/components/messages/goodbye-msg' -components: - messages: - hello-msg: - payload: - type: object - properties: - name: - type: string - sentAt: - $ref: '#/components/schemas/sent-at' - goodbye-msg: - payload: - type: object - properties: - sentAt: - $ref: '#/components/schemas/sent-at' - schemas: - sent-at: - type: string - description: The date and time a message was sent. - format: datetime - securitySchemes: - user-password: - type: userPassword`} - - -The example above shows how to specify that your server (a Kafka broker) requires a user and a password to establish a connection. Let's break this down: - -1. There's a new property in the server object called `security`. It's an array and can contain multiple security mechanisms. You chose to add one called "user-password". This is simply a memorable name that you give to this `security` scheme. Whatever name you choose, it must be defined in the `components/securitySchemes` section. You might have also noticed its value is an empty array. That's because some security schemes allow for extra configuration. Since this is not the case in this example, leave the array empty. -2. We've added a new section called `securitySchemes` under `components`. Inside it, you can find the definition of your `user-password` mechanism. This section makes it clear that you're speaking about a `user/password` mechanism, which is the `type: userPassword` in line 44. - - - -There are many more security schemes. Learn more about them here. - - - -## Conclusion - -You're now able to define what security mechanisms your application needs to connect to the server. You've seen how to define the requirement of a user and a password, which is the most common use case. - -At this point, you know AsyncAPI well enough to create a simple `Hello world application`. However, real use cases are more complicated than that. The following tutorials can teach you how to create real-world use cases, from zero to production. diff --git a/pages/docs/tutorials/getting-started/servers.md b/pages/docs/tutorials/getting-started/servers.md deleted file mode 100644 index 32337395516..00000000000 --- a/pages/docs/tutorials/getting-started/servers.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Servers" -date: 2019-04-03T10:56:52+01:00 -menu: - docs: - parent: 'getting-started' -weight: 110 ---- - -In the previous lesson, you learned how to create the definition of a simple [Hello World application](/docs/getting-started/hello-world). Let's take it from there. - -In this article, you'll learn how to add `servers` to your AsyncAPI document. Adding and defining servers is useful, because it specifies where and how to connect. The connection facilitates where to send and receive messages. - - -{`asyncapi: 2.5.0 -info: - title: Hello world application - version: '0.1.0' -servers: - production: - url: broker.mycompany.com - protocol: amqp - description: This is "My Company" broker. -channels: - hello: - publish: - message: - payload: - type: string - pattern: '^hello .+$'`} - - -You've now added a new section called `servers` in your AsyncAPI document. - -You might have noticed that our example mentions `amqp`. This protocol is very common and was popularized by RabbitMQ (among others). We picked `amqp` for our example, but you can use any protocol. The most common protocols used are `mqtt` (widely adopted by the Internet of Things and mobile apps), `kafka` (popular for its streaming solution), `ws` (WebSockets are frequently used in browsers), and `http` (used in HTTP streaming APIs). - - - -The `servers` section defines where your application should connect to start sending and receiving messages. - -1. If you are using a broker-centric architecture such as Kafka or RabbitMQ, usually you specify the URL of the broker. -2. If you have the classic client-server model such as for REST APIs, then your `server` should be the URL of the server. - - - -## Conclusion - -Now you know where `Hello world application` connects to and you can start receiving `hello {name}` messages. - -In the next chapter, you'll learn how to add security requirements to your server. diff --git a/pages/docs/tutorials/streetlights-interactive.md b/pages/docs/tutorials/streetlights-interactive.md deleted file mode 100644 index 405dcee1d29..00000000000 --- a/pages/docs/tutorials/streetlights-interactive.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Streetlights - Interactive (Alpha)' -description: Interactive version of the original Streetlights tutorial. -weight: 180 ---- - ->tl;dr -Please try out [this](https://killercoda.com/asyncapi/scenario/streetlight-tut) interactive tutorial and let us know what you think, as we plan to have all the docs written this way. - -We created an interactive tutorial using [KillerCoda](https://killercoda.com). It is another version of the [Streetlights](./streetlights.md) tutorial that will always work for you no matter what operating system you have. -Please become our alpha testers of the tutorial: - -1. Go through the tutorial [here](https://killercoda.com/asyncapi/scenario/streetlight-tut) -2. Let us know what you think using the channel that works for you the best: - - [Slack](https://www.asyncapi.com/slack-invite/) - - [Twitter](https://twitter.com/AsyncAPISpec) - - [GitHub Issue](https://github.com/asyncapi/website/issues/) diff --git a/pages/docs/tutorials/studio-document-validation.md b/pages/docs/tutorials/studio-document-validation.md deleted file mode 100644 index 199189dfc28..00000000000 --- a/pages/docs/tutorials/studio-document-validation.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "Validate AsyncAPI document with Studio" -description: This tutorial will teach you how to validate AsyncAPI documents using the AsyncAPI Studio tool. -weight: 120 ---- - -## Introduction -This tutorial will teach you how to validate AsyncAPI documents using the [AsyncAPI Studio tool](https://studio.asyncapi.com/). - -You will start with a broken AsyncAPI document and troubleshoot via console errors step-by-step until we end up with a valid AsyncAPI document. This process will illustrate how to identify [`REQUIRED` properties in AsyncAPI documents](https://www.asyncapi.com/docs/reference/specification/latest#A2SObject). - -## Background context -An AsyncAPI document is a file that defines and annotates the different components of a specific Event-Driven API. The format of the file must be JSON or YAML. You can use this document to generate both documentation and code. - -The AsyncAPI Studio tool allows you to develop an AsyncAPI document, validate it, preview it, convert it to the latest version, and visualize event flows. - - - -If you did not follow the previous tutorial and do not have an `asyncapi.yaml` file ready, then generate one using `asyncapi new --example=tutorial.yml --no-tty` command. - - - -Now let's experiment with an invalid file to see how errors are displayed and how to make that file valid again. - -## Copy invalid AsyncAPI document -Let's pretend we have an invalid AsyncAPI document. - -1. Open [Studio](https://studio.asyncapi.com/). - - - -You can also skip the step below by clicking on New File in Studio and opening the Invalid Example template in the tutorials section. - - - -2. Copy and paste the below invalid AsyncAPI document: - -```yaml -asyncapi: '1.0.0' -info: - title: Streetlights API - version: '1.0.0' - license: - name: Apache 2.0 - url: 'https://www.apache.org/licenses/LICENSE-2.0' -servers: - mosquitto: - url: mqtt://test.mosquitto.org - protocol: mqtt -channels: - light/measured: - publish: - summary: Inform about environmental lighting conditions for a particular streetlight. - operationId: onLightMeasured - message: - name: LightMeasured - payload: - type: object - properties: - id: - type: integer - minimum: true - description: Id of the streetlight. - lumens: - type: integer - minimum: 0 - description: Light intensity measured in lumens. - sentAt: - type: integer - format: date-time - description: Date and time when the message was sent. - ``` - -## Troubleshoot Studio errors -Let's fix the errors one by one until we end up with a valid AsyncAPI document. - -1. You can see the error message on the screen: `Empty or invalid document. Please fix errors/define AsyncAPI document.` - -2. Open diagnostics, you can see more information related to your errors. - -3. Fix the incorrect AsyncAPI specification number to `2.5.0`. - -```yaml -asyncapi: '2.5.0' -info: - title: Account Service - version: 1.0.0 - ``` - -Notice how description property is missing; that doesn't make the AsyncAPI document invalid, but it's always better to include. - - -4. Read the next error: `must be number`. Fix the `minimum` by changing it to: `0`. - -```yaml - properties: - id: - type: integer - minimum: 0 -``` -5. You see three errors: -- must be equal to one of the allowed values -- must be array -- must match a schema in `anyOf` - -`anyOf` means it should match any one the above schemas then it is valid. - -Now let's fix this error by changing the type to `string` - -```yaml - sentAt: - type: string - format: date-time - description: Date and time when the message was sent. -``` - -6. Congratulations! You identified and fixed all the errors, and now have a valid AsyncAPI document. - -## Summary -This tutorial taught us how to validate an AsyncAPI document using the AsyncAPI Studio tool. We also learned to troubleshoot an invalid AsyncAPI document by following the error message directions in diagnostics. In doing so, we learned how to identify `REQUIRED` properties in all AsyncAPI documents. - -## Next steps -Now that you have completed this tutorial, go ahead to learn [generate AsyncAPI messages (events)](https://asyncapi.com/docs/tutorials/generate-code) which you will be sending to your application. - -You may also enjoy reading our [AsyncAPI document validation guide](https://asyncapi.com/docs/guides/validate). - ---- diff --git a/pages/tools/parsers.js b/pages/tools/parsers.js index 4b8d6df7636..047c0038e52 100644 --- a/pages/tools/parsers.js +++ b/pages/tools/parsers.js @@ -55,7 +55,7 @@ export default function ParsersPage() { npm install @asyncapi/parser {renderButtons()} - + {getCode()} @@ -68,26 +68,32 @@ function getCode() { return `import { parse } from '@asyncapi/parser' const doc = await parse(\` - asyncapi: '2.6.0' - info: - title: Example - version: '1.0.0' - channels: - example-channel: - subscribe: - message: - payload: - type: object - properties: - exampleField: - type: string - exampleNumber: - type: number - exampleDate: - type: string - format: date-time +asyncapi: '3.0.0' +info: + title: Example + version: '1.0.0' +channels: + example: + address: example-channel + messages: + example: + payload: + type: object + properties: + exampleField: + type: string + exampleNumber: + type: number + exampleDate: + type: string + format: date-time +operations: + example: + action: send + channel: + $ref: '#/channels/example' \`) console.log(doc.info().title()) // => Example` -} \ No newline at end of file +}