jcmellado / markdown-template Goto Github PK
View Code? Open in Web Editor NEWMarkdown template for the AsyncAPI Generator. Generated files can be used to create static HTML websites with Slate or shins.
License: MIT License
markdown-template's People
Contributors
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
Stargazers
Watchers
markdown-template's Issues
Add a description column to describe parameters in tables
This already was done for binding tables, add the column in other tables.
See #6
Message traits are not applied when using oneOf on channels
The AsyncAPI Generator returns contentType: undefined when using the following YAML file:
asyncapi: 2.0.0
info:
title: Bug
version: 1.0.0
channels:
test:
subscribe:
message:
oneOf:
- $ref: "#/components/messages/test"
components:
messages:
test:
payload:
type: string
traits:
- $ref: "#/components/messageTraits/commons"
messageTraits:
commons:
contentType: application/json
If the oneOf condition is removed then the AsyncAPI Generator returns the expected application/json value.
Table of messages is not well formatted
When a channel has subscribe and publish the table of messages is not well formatted.
Add a parameter to add a Table of Contents to the Markdown document
Example:
-p tocEnabled=true
A Table of Contents (ToC) must be added to the Markdown document when the value of this parameter is true.
Or use a different approach:
-p tocLevel=1
Allowed values:
0: ToC is not added1: ToC is added, main sections (servers, channels, ...)2: ToC is added, main and secondary sections (servers, servers.variables, servers.bindings, ..., channels, channels...)
Add some parameters to control the subsections to be added for each section of the Markdown document
Example:
-p sections.servers=variables,security,bindings
A new parameter should be added por each section:
- servers
- channels
- messages
- security
- tags
- license
- termsOfService
- contact
But note that some sections don't really have subsections.
Add a description column to the bindings parameters table
Currently the binding parameters table only contains the name of the parameters and their values.
Example:
| Parameter | Value |
|---|---|
| Client Id | guest |
| Clean session | false |
A new "Description" column could be added to improve the documentation:
| Parameter | Value | Description |
|---|---|---|
| Client Id | guest | The client identifier. |
| Clean session | false | Whether to create a persistent connection or not. When false, the connection will be persistent. |
Add external documentation field on schemas
The AsyncAPI Schema Object contains a externalDocs field.
https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject
Retrieve the value and display it in the column "Description".
Links to messages and security sections
The channels section has a messages subsection. This subsection lists messages. Each message in the list could be a link.
Other subsections, like the security one, could use links too.
Add message parameter to MQTT server bindings
Add a parameter to specify the name of the Markdown file
Example:
-p output=production.md
AsyncAPI Generator Hooks Documentation:
https://github.com/asyncapi/generator/blob/master/docs/authoring.md#hooks
Improve Markdown document layout
It's hard to identity the start and end of some sections.
If/then based field definitions are not rendered correctly.
In the asynAPI below, there is a conditional expression for inclusion of the field extraDimensions. The If then statements are being rendered into the
asyncapi: 2.6.0
id: 'urn:com:precisely:onboarding:consumption'
info:
title: DI Suite - Consumption
description: |
Event messaging for DI Suite consumption reporting.
version: 1.1.0
defaultContentType: application/json
channels:
onboarding-consumption:
publish:
operationId: publishConsumptionEvent
summary: Notify of application usage for consumption reporting purposes.
message:
$ref: '#/components/messages/consumptionEvent'
components:
messages:
consumptionEvent:
name: consumptionEvent
title: Consumption Event
headers:
$ref: '#/components/schemas/message-header'
correlationId:
$ref: '#/components/correlationIds/defaultCorrelationId'
payload:
$ref: '#/components/schemas/consumption'
tags:
- name: onboarding
correlationIds:
defaultCorrelationId:
description: Default Correlation ID
location: $message.header#/correlationId
schemas:
message-header:
type: object
required:
- type
- schemaVersion
- messageId
properties:
type:
type: string
description: >-
The type of the message. Allows for selection of proper
deserializer.
const: ConsumptionEvent
schemaVersion:
type: integer
description: >-
The version of the message. Allows for backward compatibility as
the message format is evolved.
messageId:
type: string
description: >-
A globally unique message ID (GUIDV4) that may be used for
de-duplication or debugging.
format: uuid
maxLength: 38
correlationId:
type: string
description: >-
An optional globally unique value used to correlate the message with
the initial resource that led to the creation of the event, such as
the x-request-id of an HTTP request.
maxLength: 38
consumption:
type: object
required:
- workspaceId
- metricType
- value
- producer
- eventStart
- eventEnd
properties:
workspaceId:
type: string
description: TBD
minLength: 12
maxLength: 16
metricType:
type: string
description: >-
The type name of the metric being reported (ex. observations,
rowsSynchronized, totalUsers, activeRows))
maxLength: 255
value:
type: number
description: The value to be aggregated.
min: 1
maximum: 18446744073709552000
producer:
type: string
description: The name of the application sending the event
enum:
- observability
- geo-addressing
eventStart:
type: string
description: ISO8601 UTC date-time string using Z zone designator
format: date-time
pattern: >-
^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z)$
eventEnd:
type: string
description: >-
ISO8601 UTC date-time string using Z zone designator. An instant is
represented by setting the eventEnd value to the same as the
eventStart value.
format: date-time
pattern: >-
^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z)$
dimensionType:
type: string
enum:
- GeoAddressingRoyalty
description: >-
An optional type name to indicate the contents of the extra
dimensions key-value bucket. The extraDimensions property is
required if this value is not null. New values must be coordinated
with the onboarding team.
if:
properties:
dimensionType:
pattern: (.|\s)*\S(.|\s)*
then:
required:
- extraDimensions
properties:
extraDimensions:
type: array
items:
type: object
required:
- key
- value
minItems: 1
uniqueItems: true
properties:
key:
type: string
value:
type: string
Output
##### Payload
| Name | Type | Description | Value | Constraints | Notes |
|----------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|--------------------------------------------------------------|---------------------------------------|
| (root) | object | - | - | - | **additional properties are allowed** |
| workspaceId | string | TBD | - | [ 12 .. 16 ] characters | **required** |
| metricType | string | The type name of the metric being reported (ex. observations, rowsSynchronized, totalUsers, activeRows)) | - | <= 255 characters | **required** |
| value | number | The value to be aggregated. | - | <= 18446744073709552000 | **required** |
| producer | string | The name of the application sending the event | allowed (`"observability"`, `"geo-addressing"`) | - | **required** |
| eventStart | string | ISO8601 UTC date-time string using Z zone designator | - | format (`date-time`), pattern (`^(?:[1-9]\d{3}-(?:(?:0[1-9]\ | 1[0-2])-(?:0[1-9]\|1\d\|2[0-8])\|(?:0[13-9]\|1[0-2])-(?:29\|30)\|(?:0[13578]\|1[02])-31)\|(?:[1-9]\d(?:0[48]\|[2468][048]\|[13579][26])\|(?:[2468][048]\|[13579][26])00)-02-29)T(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z)$`) | **required** |
| eventEnd | string | ISO8601 UTC date-time string using Z zone designator. An instant is represented by setting the eventEnd value to the same as the eventStart value. | - | format (`date-time`), pattern (`^(?:[1-9]\d{3}-(?:(?:0[1-9]\ | 1[0-2])-(?:0[1-9]\|1\d\|2[0-8])\|(?:0[13-9]\|1[0-2])-(?:29\|30)\|(?:0[13578]\|1[02])-31)\|(?:[1-9]\d(?:0[48]\|[2468][048]\|[13579][26])\|(?:[2468][048]\|[13579][26])00)-02-29)T(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z)$`) | **required** |
| dimensionType | string | An optional type name to indicate the contents of the extra dimensions key-value bucket. The extraDimensions property is required if this value is not null. New values must be coordinated with the onboarding team. | allowed (`"GeoAddressingRoyalty"`) | - | - |
| if | - | - | - | - | **additional properties are allowed** |
| if.dimensionType | - | - | - | pattern (`(.\ | \s)*\S(.\|\s)*`) | **additional properties are allowed** |
| then | - | - | - | - | **additional properties are allowed** |
| then.extraDimensions | array<object> | - | - | - | **required** |
| then.extraDimensions.key | string | - | - | - | **required** |
| then.extraDimensions.value | string | - | - | - | **required** |
Improve the Table Of Content filter
The filter can be improved, like the bookmarks one See #26
Improve bookmark filters
Bookmarks are using three filters, I think that the code could be improved and use only one filter instead.
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.