As a Telegram Bot Developer, I'd like Telegram Bot API Documentation to have a Machine-readable (or even Human-readable) API Scheme to have possibility for automatic generation API Interaction Libraries not depending on the programming language.
This will give developers some benefits like:
Maintaining the codebase up-to-date.
Less time required to maintain this codebase.
And finally, ability to scale API Interaction Library
functional easier.
API Scheme requirements:
Methods
1.1. Detailed information about method parameters,
documentation for method parameters and for the method itself.
1.2. Legible parameter types and method return type
documentations.
Models
2.1. Detailed information about model fields, detailed
documentation for each field.
2.2. Information about class inheritors (if model declared as
an abstract) and their documentation.
2.3. Legible fields types and possible types (if field type
is abstract model).
Provided Schema doesn’t cover all API possibilities yet
(like multiple method call variants, where method returns objects with
different types, depending on the call variant, etc.), and will improving
during the discussion of this proposal (if it won’t be closed).