Generator: generate schema document

[arthurparahyba]

Hi, i started to use asyncapi to document my asynchronous api last week and i was asked to create a document with the schema. The goal was to generate a pdf to send to the partners in a formal document. Based in a html-template, i create a very simple html-schema-template (@arthurparahyba/html-schema-template). It generates html, but, using the browser, you can export the html as a pdf if you want. Was amazing to me face the fact that it was realy easy to do and to integrate with async-generator. But i need a help to do three things:
1) Create different descriptions to properties than the description of the type definition. I create an outside solution using the x-properties, for example: (x-name: "The name of the user") is show as a description of the property (name: $ref: "components/schemas/NameType") in html-schema-template. I understand that its not correct.
2) Define a property as an array of an object type.
3) Generate a xml example too.

Thanks.

[github-actions[bot]]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue.

Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

Hi @arthurparahyba. Awesome to hear you like our generator.

Could you please specify how exactly can we help you?

1. I didn't get what you try to achieve with specification extensions, could you share some example of what you have?
2. What property do you want to define as an object type?
3. xml? you mean asyncapi file in xml instead of json or yaml?

[arthurparahyba]

Hi @derberg.
1) To create services and clients, i understand that this descriptions is not so important, but i belive that it's good for documentation. (And i need it too) See the comments in example below:

components:
  schemas:
    Pet:
      type: object
      properties:
        name: 
          description: The pet's name //I want to access this description with {{ prop.description() }}
          $ref: "#/components/schemas/identValue"

    User:
      type: object
      properties:
        login: 
          description: The login of the user in authentication service //and this
          $ref: "#/components/schemas/identValue"

    IdentValue:
      description: The indentification value... //and this **too**
      type: string
      format: "^[A-Za-z]{5,30}$"

2) The problem is: when i set a property as an array, i lost the value of the schema name's of the property.

components:
  schemas:
    Pet:
      type: object
      properties:
        name: //{{ prop.uid() }} == array (Bad)
          type: array
          name: $ref: "#/components/schemas/identValue"

components:
  schemas:
    Pet:
      type: object
      properties:
        name: // {{ prop.uid() }} == identValue (Good)
        $ref: "#/components/schemas/identValue"

To make it clear, i added a pdf in this comment with the schema of the playground example. It was generated with the html-schema-template. In turnOnOffPayload, the sentAt property is showed as an array (bad), but in lightMeasuredPayload, the sentAt references to a sentAt type (good). When a property is typed as an array, i can't find the schema type's name because the value of {{ prop.uid() }} is just array.

3) I just need a help to understand how the html-template module creates a json example. If it's simple, maybe i can create a tool to generate a xml example and solve my problem easely. Thanks

playground-example-schema.pdf

[derberg]

let me as some further questions:

1. You can have a description on schema object level and specific property level:

  schemas:
    lightMeasuredPayload:
      type: object
      description: my description
      properties:
        lumens:
          type: integer
          minimum: 0
          description: my another description

When I try it you in our playgroud I can see that both descriptions are parsed and rendered

1. This is how I would work with arrays

  schemas:
    lightMeasuredPayload:
      type: object
      description: my description
      properties:
        lumens:
          type: array
          description: Light intensity measured in lumens.
          items: 
             type: string
        sentAt:
          $ref: "#/components/schemas/sentAt"

and it renders well in the playground
3. There are 2 ways to create examples:
- they can be generated from the schema, and this is what is used by default with this template filter https://github.com/asyncapi/html-template/blob/master/filters/all.js#L150 using OpenAPISampler library
- you can also provide examples explicitly as message examples https://www.asyncapi.com/docs/specifications/2.0.0/#a-name-messageobject-a-message-object and read them for the AsyncAPI file

If I got your explanation totally wrong, first of all sorry, but could you maybe explain on default example from the playground? because above you write about Pet and then props from our streetlight example.

[arthurparahyba]

Thanks, @derberg! Your answer solve all my questions.

[derberg]

@arthurparahyba awesome, glad I could help. I will close this issue for now. Feel free to create another one once you need more help