Missing required fields in the swagger json file

[Gara-Dorta]

The problem

There is no required field in the json file that is generated for the swagger documentation. If I use it to generate code from it, then all fields are marked as optional, which is not true.

Digging a bit into it, it seems that swag should be ran with swag init --requiredByDefault. This adds the fields to the required category except for the ones marked as omitempty.

I'm happy to make a PR for it but I'm rather confused about it. Most of the omitempty annotations don't seem to be used. For example, for the SendMessageV2 the one with omitempty is in:

signal-cli-rest-api/src/client/client.go

Line 544 in eb34542

EditTimestamp *int64 `json:"edit-timestamp,omitempty"`

but the one that makes it to swagger is this one:

signal-cli-rest-api/src/api/api.go

Line 134 in eb34542

EditTimestamp *int64 `json:"edit_timestamp"`

Are the annotations in client.go doing anything? Should they be removed and placed in api.go? Or should they be copied over?

Are you using the latest released version?

• Yes

Have you read the troubleshooting page?

• Yes

What type of installation are you running?

signal-cli-rest-api Docker Container

In which mode are you using the docker container?

Normal Mode

What's the architecture of your host system?

x86-64

Additional information

No response

[bbernhard]

The

The problem

There is no required field in the json file that is generated for the swagger documentation. If I use it to generate code from it, then all fields are marked as optional, which is not true.

Digging a bit into it, it seems that swag should be ran with swag init --requiredByDefault. This adds the fields to the required category except for the ones marked as omitempty.

I'm happy to make a PR for it but I'm rather confused about it. Most of the omitempty annotations don't seem to be used. For example, for the SendMessageV2 the one with omitempty is in:

signal-cli-rest-api/src/client/client.go

This struct defines the JSON payload that is sent to signal-cli.

Line 544 in eb34542
EditTimestamp *int64 json:"edit-timestamp,omitempty"
but the one that makes it to swagger is this one:

signal-cli-rest-api/src/api/api.go

And that struct defines the payload that is exposed to the user of the API.

That was done intentionally to decouple the user facing REST API from the API that signal-cli requires (e.g signal-cli sometimes releases breaking changes - the decoupling makes it possible to keep the REST API stable and backwards compatible in that case).

[Gara-Dorta]

Thanks for explaining. So that means that the api.go annotations are still underdetermined and the swagger json should mark the values that the api actually has as required / omitted.

So for the class it should go from

type SendMessageV2 struct {
	Number            string              `json:"number"`
	Recipients        []string            `json:"recipients"`
	Recipient         string              `json:"recipient" swaggerignore:"true"` //some REST API consumers (like the Synology NAS) do not support an array as recipients, so we provide this string parameter here as backup. In order to not confuse anyone, the parameter won't be exposed in the Swagger UI (most users are fine with the recipients parameter).
	Message           string              `json:"message"`
	Base64Attachments []string            `json:"base64_attachments" example:"<BASE64 ENCODED DATA>,data:<MIME-TYPE>;base64<comma><BASE64 ENCODED DATA>,data:<MIME-TYPE>;filename=<FILENAME>;base64<comma><BASE64 ENCODED DATA>"`
	Sticker           string              `json:"sticker"`
	Mentions          []ds.MessageMention `json:"mentions"`
	QuoteTimestamp    *int64              `json:"quote_timestamp"`
	QuoteAuthor       *string             `json:"quote_author"`
	QuoteMessage      *string             `json:"quote_message"`
	QuoteMentions     []ds.MessageMention `json:"quote_mentions"`
	TextMode          *string             `json:"text_mode" enums:"normal,styled"`
	EditTimestamp     *int64              `json:"edit_timestamp"`
	NotifySelf        *bool               `json:"notify_self"`
	LinkPreview       *ds.LinkPreviewType `json:"link_preview"`
	ViewOnce          *bool               `json:"view_once"`
}

to

type SendMessageV2 struct {
	Number            string              `json:"number"`
	Recipients        []string            `json:"recipients,omitempty"`
	Recipient         string              `json:"recipient" swaggerignore:"true"` //some REST API consumers (like the Synology NAS) do not support an array as recipients, so we provide this string parameter here as backup. In order to not confuse anyone, the parameter won't be exposed in the Swagger UI (most users are fine with the recipients parameter).
	Message           string              `json:"message"`
	Base64Attachments []string            `json:"base64_attachments" example:"<BASE64 ENCODED DATA>,data:<MIME-TYPE>;base64<comma><BASE64 ENCODED DATA>,data:<MIME-TYPE>;filename=<FILENAME>;base64<comma><BASE64 ENCODED DATA>"`
	Sticker           string              `json:"sticker,omitempty"`
	Mentions          []ds.MessageMention `json:"mentions,omitempty"`
	QuoteTimestamp    *int64              `json:"quote_timestamp,omitempty"`
	QuoteAuthor       *string             `json:"quote_author,omitempty"`
	QuoteMessage      *string             `json:"quote_message,omitempty"`
	QuoteMentions     []ds.MessageMention `json:"quote_mentions,omitempty"`
	TextMode          *string             `json:"text_mode" enums:"normal,styled",omitempty"`
	EditTimestamp     *int64              `json:"edit_timestamp,omitempty"`
	NotifySelf        *bool               `json:"notify_self,omitempty"`
	LinkPreview       *ds.LinkPreviewType `json:"link_preview,omitempty"`
	ViewOnce          *bool               `json:"view_once,omitempty"`
}

leaving only the number and message as required fields, which would produce a swagger json like so

        "api.SendMessageV2": {
            "type": "object",
            "properties": {
                "base64_attachments": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                ,
                "edit_timestamp": {
                    "type": "integer"
                },
               ...
            "required": [
               "number",
               "message"
            ]

Does that makes sense to you too?

[bbernhard]

Sounds good to me! Thanks for looking into this!