NetTalk Central

Author Topic: Add to API auto documentation  (Read 1507 times)

ProperGary

  • Newbie
  • *
  • Posts: 19
    • View Profile
    • Email
Add to API auto documentation
« on: April 04, 2022, 03:45:47 AM »
My API returns a queue, but the queue in Local Data is defined using a Base Type that is defined in a separate class file.

The Auto Documentation therefore only picks up the Queue name and Description, the individual queue columns with their names, type and description don't get included.

Is there an embed point where I can manually add column details to the documentation or a way to get the documentation to look to the class definition?

Bruce

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 11155
    • View Profile
Re: Add to API auto documentation
« Reply #1 on: April 05, 2022, 03:27:54 AM »
There are more embed points added for 12.39, but the question is more involved than it seems at first glance.

Sure you can add text to the description, but that does nothing for the other auto-generated things, like the WSDL file, the example code or the Try It Now. So at best the extra documentation is an improvement, but does not solve the real problem.

The real problem is that the documentation is generated at compile time, from the data pad etc, whereas it would be better to generate it at runtime, from the actual structures. That change is a big job though, and is waiting on the release of xFiles 4, and would in turn make use of the CapeSoft Reflection class and so on. All of this is currently scheduled for NetTalk 13 though, it won't happen as a NetTalk 12 update - it's too complex a change.

Cheers
Bruce

ProperGary

  • Newbie
  • *
  • Posts: 19
    • View Profile
    • Email
Re: Add to API auto documentation
« Reply #2 on: April 19, 2022, 05:48:52 AM »
Hi Bruce,

My problem is that I can't see how to define my data structure in the data pad
Code: [Select]
JSON data structure
"ShippingCodes": [
{
  ?code?: ?DHL?,
  ?description?: ?DHL Limited?,
  ?service?: [
    {
      ?code?: ?NEXTDAY?,
      ?type?: ?Next Day?
    }
    {
      ?code?: ?PRE1?,
      ?type?: ?Before 1pm?
    }
    {
      ?code?: ?SAS1?,
      ?type?: ?Slow and Steady?
    }
  ]
}
{
  ?code?: ?RM?,
  ?description?: ?Royal Mail?,
  ?service?: [
    {
      ?code?: ?FIRST?,
      ?type?: ?Standard First Class?
    }
    {
      ?code?: ?PRIORTY?,
      ?type?: ?Priority Next Day?
    }   
  ]
}
]

So I need a Queue referenced within a Queue, which I can't work out a way of doing in the data pad, although I can do it in code:

Code: [Select]
shippingCodesQueue  QUEUE,TYPE
code                         STRING(20) !Shipping Code
description                STRING(100) !Shipping Code Description
services          &serviceListType         !Related Services
END


!Service list Structure
serviceListType        QUEUE,TYPE
code                       STRING(20) !Shipping Service Code
description              STRING(100) !Shipping Service Description
END


Is there some trick or work around to define the above in the data pad?

Bruce

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 11155
    • View Profile
Re: Add to API auto documentation
« Reply #3 on: April 20, 2022, 03:26:35 AM »
The data pad lets you add a field of type Queue (with Reference automatically ticked on) into a queue....
So I'm not sure I'm understanding your question. Perhaps a good question for the webinar next week (there isn't one tomorrow.)

Bruce

ProperGary

  • Newbie
  • *
  • Posts: 19
    • View Profile
    • Email
Re: Add to API auto documentation
« Reply #4 on: April 20, 2022, 06:35:39 AM »
Hi Bruce,

Happy to go through in next weeks webinar, my issue is that I can define a field of type Queue in a queue, but I don't see a way to tell it that the Queue is of type "shippingServices" so the documentation does not know what to show.

See images attached.

I've built this as a demo project, which I'll email you as attaching failed.

Alberto

  • Hero Member
  • *****
  • Posts: 1843
    • MSN Messenger - alberto-michelis@hotmail.com
    • View Profile
    • ARMi software solutions
    • Email
Re: Add to API auto documentation
« Reply #5 on: April 21, 2022, 03:38:48 AM »
Hi ProperGary,

You need to choose TYPE , not QUEUE and then choose the queuetype.

Regards
-----------
Regards
Alberto