Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update parser-api #64

Merged
merged 3 commits into from
Jun 23, 2022
Merged

docs: update parser-api #64

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
131c76b
docs: add traits
magicmatatjahu May 5, 2022
645aa9f
Merge branch 'master' into add-traits
magicmatatjahu Jun 23, 2022
afb2f0f
after review
magicmatatjahu Jun 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 76 additions & 15 deletions docs/v1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# AsyncAPI Parser API v1.0.0-alpha.2
# AsyncAPI Parser API v1.0.0-alpha.3

## AsyncAPIDocument
- channels() : `Channels`
- defaultContentType() : `string` | `undefined`
Expand Down Expand Up @@ -43,10 +44,14 @@
- servers() : `Servers`

## ChannelParameter
- id() : `string`
- hasDescription() : `boolean`
- description() : `string` | `undefined`
- hasSchema(): `boolean`
- schema() : `Schema` | `undefined`
- hasLocation() : `boolean`
- location(): `string` | `undefined`
- extensions() : `Extensions`
- id() : `string`
- schema() : `Schema`

## ChannelParameters
- all() : `ChannelParameter[]`
Expand Down Expand Up @@ -140,12 +145,45 @@
- id() : `string`
- name() : `string` | `undefined`
- operations() : `Operations`
- hasPayload() : `boolean`
- payload() : `Schema | any`
- schemaFormat() : `string`
- servers() : `Servers`
- summary() : `string` | `undefined`
- tags() : `Tags`
- title() : `string` | `undefined`
- traits(): `MessageTraits`

## MessageTraits
- all() : `MessageTrait[]`
- get(id: `string`) : `MessageTrait` | `undefined`
- has(id: `string`) : `boolean`
- isEmpty() : `boolean`

## MessageTrait
- bindings() : `Bindings`
- channels() : `Channels`
- contentType() : `string`
- correlationId() : `CorrelationId` | `undefined`
- description() : `string` | `undefined`
- examples() : `Map[string, any][]`
- extensions() : `Extensions`
- hasCorrelationId() : `boolean`
- hasDescription() : `boolean`
- hasHeaders() : `boolean`
- hasKnownSchemaFormat() : `boolean`
- hasName() : `boolean`
- hasSummary() : `boolean`
- hasTitle() : `boolean`
- headers() : `Schema` | `undefined`
- id() : `string`
- name() : `string` | `undefined`
- operations() : `Operations`
- schemaFormat() : `string`
- servers() : `Servers`
- summary() : `string` | `undefined`
- tags() : `Tags`
- title() : `string` | `undefined`

## OAuthFlow
- authorizationUrl() : `string` | `undefined`
Expand All @@ -166,6 +204,15 @@
- implicit() : `OAuthFlow` | `undefined`
- password() : `OAuthFlow` | `undefined`

## Operations
- all() : `Operation[]`
- filterBy(filter : `(operation: Operation) => boolean`) : `Operation[]`
- filterBySend() : `Operation[]`
- filterByReceive() : `Operation[]`
- get(id: `string`) : `Operation` | `undefined`
- has(id: `string`) : `boolean`
- isEmpty() : `boolean`

## Operation
- bindings() : `Bindings`
- channels() : `Channel[]`
Expand All @@ -175,25 +222,39 @@
- hasDescription() : `boolean`
- hasSummary() : `boolean`
- id() : `string`
- isApplicationPublishing() : `boolean`
- isApplicationSubscribing() : `boolean`
- isClientPublishing() : `boolean`
- isClientSubscribing() : `boolean`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't make sense to include isSend() and isReceive() ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In 2.x.x these methods would then have a different meaning, so for now I prefer not to add these methods and see how 3.x.x will look like and then we will add the appropriate methods.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But here we are building an API based on intents, and those are still valid. I think we should add them and, for 2.x.x, return only the value it should be returned, without the application or client perspective.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you suggest isSubscribing, isPublishing?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I suggest we do, at implementation level:

2.x.x:

  • isSend() -> this.action === publish
  • isReceive() -> this.action === subscribe

3.x.x:

  • isSend() -> this.action === send
  • isReceive() -> this.action === receive

Copy link
Member Author

@magicmatatjahu magicmatatjahu May 9, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smoya Thanks, however in in the 2.x.x we should switch publish/subscribe meaning, because isSend and isReceive describes operation from application point of view, not user, so publish -> receive (user publishes something, so app receives it), but subscribe -> send (user subscribs to something, so app sends it to the user), but I could be wrong, so please correct me.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I thought about this but I thought we could just follow the perspective or point of view each spec version has:

  • 2.x.x: described from the point of view of the client
  • 3.x.x: described from the point of view of the application

However, if we start documenting each method on the Parser-API, it could be convenient to clarify what is the point of view of the API itself, which aligned with >=3.x.x, It would be the application's one.

I think I can agree we should go further and do what you suggest @magicmatatjahu, to be completely strict on meanings and explicitly consider send always means the application is sending a message, no room for interpretation 👍 .

WDYT @fmvilas @jonaslagoni ?

- messages() : `Message[]`
- servers() : `Server[]`
- summary() : `string` | `undefined`
- tags() : `Tags`
- type() : `enum{'ClientSubscribing', 'ClientPublishing', 'ApplicationSubscribing', 'ApplicationPublishing}`
- security() : `Array<Record<string, { schema: SecurityScheme, scopes: Array<string> }>>`
- isSend(): `boolean`
- isReceive(): `boolean`
- action() : `enum{'Send', 'Receive', 'Publish', 'Subscribe'}`
- traits: `OperationTraits`

## Operations
- all() : `Operation[]`
- filterBy(filter : `(operation: Operation) => boolean`) : `Operation[]`
- filterBySend() : `Operation[]`
- filterByReceive() : `Operation[]`
- get(id: `string`) : `Operation` | `undefined`
## OperationTraits
- all() : `OperationTrait[]`
- get(id: `string`) : `OperationTrait` | `undefined`
- has(id: `string`) : `boolean`
- isEmpty() : `boolean`

## OperationTrait
- bindings() : `Bindings`
- channels() : `Channel[]`
- description() : `string` | `undefined`
- extensions() : `Extensions`
- externalDocs() : `ExternalDocument` | `undefined`
- hasDescription() : `boolean`
- hasSummary() : `boolean`
- id() : `string`
- servers() : `Server[]`
- summary() : `string` | `undefined`
- tags() : `Tags`
- security() : `Array<Record<string, { schema: SecurityScheme, scopes: Array<string> }>>`
- isSend(): `boolean`
- isReceive(): `boolean`
- action() : `enum{'Send', 'Receive', 'Publish', 'Subscribe'}`

## Schema
- $id() : `string` | `undefined`
- additionalItems : `boolean | Schema`
Expand Down Expand Up @@ -294,7 +355,7 @@
- operations() : `Operations`
- protocol() : `string` | `undefined`
- protocolVersion() : `string` | `undefined`
- securitySchemes() : `SecuritySchemes`
- security() : `Array<Record<string, { schema: SecurityScheme, scopes: Array<string> }>>`
- url() : `string` | `undefined`
- variables() : `ServerVariables`

Expand Down