Missing Documentation - Looking for contributors 🚀

[chrishubert]

This one is a lot of work,

I use Swagger Autogen (swagger-autogen)
I'm calling for potential contributors to help improve it 🥰

The syntax is quite straightforward with multiple examples across the code with an example here

Once written, it's as easy as running npm run swagger to generate the doc!

[firmanalams]

Hi, i think i can help. Can you give me an example where should i improve?

[kaua-alves-queiros]

Very good! I had already suggested doing this because I also use NSwag to generate the SDK

[avoylenko]

@kaua-alves-queiros feel free to use the forked project https://github.com/avoylenko/wwebjs-api with improved documentation.

[kaua-alves-queiros]

@avoylenko I made some adjustments directly in the swagger.json code to generate some parts correctly. I will clone the repository and try to bring these improvements to the documentation in the proper way.

[kaua-alves-queiros]

Note: I'm from dotnet and I've never used swagger this way.

from what I understand despite a lot of work it is not difficult

I managed to bring the workaround I did to generate it correctly using autogen instead of hardcoding it in swagger.json

that generated the expected result

I will take another look at the standards that are being applied in the project to ensure that it is well done and without my vices in other stacks, soon I will start sending the improvements in the documentation.

[afikri99]

Very interesting and helpful! Thanks!!!

[kaua-alves-queiros]

A few days later, I am here again. I took a look and created a draft of what we can do with the Swagger documentation.

Due to the large number of types that will be created and would clutter the structure, I separated them into files based on the controllers. Additionally, I moved those that can be used independently of controllers to the utils directory.

I created the responses for getClassInfo and getChats in the client controller, obtaining the expected result.

This is reflected both in /api-docs/

And in the SDK generation. To test it, I used my main stack, which is C#.

Auto-Generated GetChatsResponse

[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "14.1.0.0 (NJsonSchema v11.0.2.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class GetChatsResponse
{
    [Newtonsoft.Json.JsonProperty("success", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public bool Success { get; set; }

    [Newtonsoft.Json.JsonProperty("chats", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public System.Collections.Generic.ICollection<Chat> Chats { get; set; }

    private System.Collections.Generic.IDictionary<string, object> _additionalProperties;

    [Newtonsoft.Json.JsonExtensionData]
    public System.Collections.Generic.IDictionary<string, object> AdditionalProperties
    {
        get { return _additionalProperties ?? (_additionalProperties = new System.Collections.Generic.Dictionary<string, object>()); }
        set { _additionalProperties = value; }
    }
}

Auto-Generated Chat Model

[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "14.1.0.0 (NJsonSchema v11.0.2.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class Chat
{
    [Newtonsoft.Json.JsonProperty("id", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public ChatId Id { get; set; }

    [Newtonsoft.Json.JsonProperty("name", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public string Name { get; set; }

    [Newtonsoft.Json.JsonProperty("isReadOnly", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public bool IsReadOnly { get; set; }

    [Newtonsoft.Json.JsonProperty("unreadCount", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public double UnreadCount { get; set; }

    [Newtonsoft.Json.JsonProperty("timestamp", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public double Timestamp { get; set; }

    [Newtonsoft.Json.JsonProperty("archived", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public bool Archived { get; set; }

    [Newtonsoft.Json.JsonProperty("pinned", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public bool Pinned { get; set; }

    [Newtonsoft.Json.JsonProperty("muteExpiration", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public double MuteExpiration { get; set; }

    private System.Collections.Generic.IDictionary<string, object> _additionalProperties;

    [Newtonsoft.Json.JsonExtensionData]
    public System.Collections.Generic.IDictionary<string, object> AdditionalProperties
    {
        get { return _additionalProperties ?? (_additionalProperties = new System.Collections.Generic.Dictionary<string, object>()); }
        set { _additionalProperties = value; }
    }
}

Auto-Generated ChatId Model

[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "14.1.0.0 (NJsonSchema v11.0.2.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class ChatId
{
    [Newtonsoft.Json.JsonProperty("server", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public string Server { get; set; }

    [Newtonsoft.Json.JsonProperty("user", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public string User { get; set; }

    [Newtonsoft.Json.JsonProperty("_serialized", Required = Newtonsoft.Json.Required.DisallowNull, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
    public string _serialized { get; set; }

    private System.Collections.Generic.IDictionary<string, object> _additionalProperties;

    [Newtonsoft.Json.JsonExtensionData]
    public System.Collections.Generic.IDictionary<string, object> AdditionalProperties
    {
        get { return _additionalProperties ?? (_additionalProperties = new System.Collections.Generic.Dictionary<string, object>()); }
        set { _additionalProperties = value; }
    }
}

Auto-Generated GetChats Request Function

public virtual async System.Threading.Tasks.Task<GetChatsResponse> GetChatsAsync(string sessionId, System.Threading.CancellationToken cancellationToken)
{
    if (sessionId == null)
        throw new System.ArgumentNullException("sessionId");

    var client_ = _httpClient;
    var disposeClient_ = false;
    try
    {
        using (var request_ = new System.Net.Http.HttpRequestMessage())
        {
            request_.Method = new System.Net.Http.HttpMethod("GET");
            request_.Headers.Accept.Add(System.Net.Http.Headers.MediaTypeWithQualityHeaderValue.Parse("application/json"));

            var urlBuilder_ = new System.Text.StringBuilder();
            if (!string.IsNullOrEmpty(_baseUrl)) urlBuilder_.Append(_baseUrl);
            urlBuilder_.Append("client/getChats/");
            urlBuilder_.Append(System.Uri.EscapeDataString(ConvertToString(sessionId, System.Globalization.CultureInfo.InvariantCulture)));

            PrepareRequest(client_, request_, urlBuilder_);

            var url_ = urlBuilder_.ToString();
            request_.RequestUri = new System.Uri(url_, System.UriKind.RelativeOrAbsolute);

            PrepareRequest(client_, request_, url_);

            var response_ = await client_.SendAsync(request_, System.Net.Http.HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
            var disposeResponse_ = true;
            try
            {
                var headers_ = new System.Collections.Generic.Dictionary<string, System.Collections.Generic.IEnumerable<string>>();
                foreach (var item_ in response_.Headers)
                    headers_[item_.Key] = item_.Value;
                if (response_.Content != null && response_.Content.Headers != null)
                {
                    foreach (var item_ in response_.Content.Headers)
                        headers_[item_.Key] = item_.Value;
                }

                ProcessResponse(client_, response_);

                var status_ = (int)response_.StatusCode;
                if (status_ == 200)
                {
                    var objectResponse_ = await ReadObjectResponseAsync<GetChatsResponse>(response_, headers_, cancellationToken).ConfigureAwait(false);
                    if (objectResponse_.Object == null)
                    {
                        throw new ApiException("Response was null which was not expected.", status_, objectResponse_.Text, headers_, null);
                    }
                    return objectResponse_.Object;
                }
                else
                {
                    var responseData_ = response_.Content == null ? null : await response_.Content.ReadAsStringAsync().ConfigureAwait(false);
                    throw new ApiException("The HTTP status code of the response was not expected (" + status_ + ").", status_, responseData_, headers_, null);
                }
            }
            finally
            {
                if (disposeResponse_)
                    response_.Dispose();
            }
        }
    }
    finally
    {
        if (disposeClient_)
            client_.Dispose();
    }
}

@chrishubert
The modifications and additions were made in my fork of the project. I need you to evaluate whether the structure being built aligns with expectations so that I can continue making improvements and adding fields, or if I should take a different approach.

🔗 GitHub - kaua-alves-queiros/whatsapp-api