[GH-ISSUE #188] Swagger file

kerem commented

2026-03-15 12:43:00 +03:00

Owner

Originally created by @swimmwatch on GitHub (Oct 14, 2023).
Original GitHub issue: https://github.com/axllent/mailpit/issues/188

Hi! Thanks for awesome alternative to MailHog project.

Can you please tell me swagger file was generated or written manually?

Originally created by @swimmwatch on GitHub (Oct 14, 2023). Original GitHub issue: https://github.com/axllent/mailpit/issues/188 Hi! Thanks for awesome alternative to MailHog project. Can you please tell me [swagger file](https://github.com/axllent/mailpit/blob/eeac32d09b681181e122e376b85759ee01fea53e/server/ui/api/v1/swagger.json#L11) was generated or written manually?

kerem closed this issue

2026-03-15 12:43:05 +03:00

kerem commented

2026-03-15 12:43:11 +03:00

Author

Owner

@axllent commented on GitHub (Oct 14, 2023):

Thanks for the kind words @swimmwatch.

The swagger file is automatically generated using "go swagger", which uses inline code comments to gather the info. Why do you ask?

@axllent commented on GitHub (Oct 14, 2023): Thanks for the kind words @swimmwatch. The swagger file is automatically generated using "go swagger", which uses inline code comments to gather the info. Why do you ask?

kerem commented

2026-03-15 12:43:16 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 14, 2023):

Currently i am working on Python SDK for Mailpit REST API. I generated SDK using OpenAPI Generator and it printed some errors:

Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 10, Warning count: 0
Errors: 
        -attribute paths.'/api/v1/messages'(put).[ids].description is unexpected
        -attribute paths.'/api/v1/search'(delete).operationId is repeated
        -attribute paths.'/api/v1/messages'(put).[ids].type is unexpected
        -attribute paths.'/api/v1/messages'(delete).[ids].type is unexpected
        -attribute paths.'/api/v1/tags'(put).[ids].type is unexpected
        -attribute paths.'/api/v1/message/{ID}/release'(post).[to].description is unexpected
        -attribute paths.'/api/v1/tags'(put).[ids].description is unexpected
        -attribute paths.'/api/v1/message/{ID}/release'(post).[to].type is unexpected
        -attribute paths.'/api/v1/messages'(delete).[ids].description is unexpected
        -attribute paths.'/api/v1/tags'(put).operationId is repeated

For example:
-attribute paths.'/api/v1/tags'(put).operationId is repeated error occurs because GET /api/v1/tags endpoint has duplicated operationId value - SetTags. I think it should be equal GetAllTags or something like that.

I think it would be cool to add validation of the generated swagger.json file at the CI level.

@swimmwatch commented on GitHub (Oct 14, 2023): Currently i am working on Python SDK for Mailpit REST API. I generated SDK using [OpenAPI Generator](https://openapi-generator.tech/) and it printed some errors: ```bash Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI). | Error count: 10, Warning count: 0 Errors: -attribute paths.'/api/v1/messages'(put).[ids].description is unexpected -attribute paths.'/api/v1/search'(delete).operationId is repeated -attribute paths.'/api/v1/messages'(put).[ids].type is unexpected -attribute paths.'/api/v1/messages'(delete).[ids].type is unexpected -attribute paths.'/api/v1/tags'(put).[ids].type is unexpected -attribute paths.'/api/v1/message/{ID}/release'(post).[to].description is unexpected -attribute paths.'/api/v1/tags'(put).[ids].description is unexpected -attribute paths.'/api/v1/message/{ID}/release'(post).[to].type is unexpected -attribute paths.'/api/v1/messages'(delete).[ids].description is unexpected -attribute paths.'/api/v1/tags'(put).operationId is repeated ``` For example: `-attribute paths.'/api/v1/tags'(put).operationId is repeated` error occurs because `GET /api/v1/tags` endpoint has duplicated `operationId` value - `SetTags`. I think it should be equal `GetAllTags` or something like that. I think it would be cool to add validation of the generated `swagger.json` file at the CI level.

kerem commented

2026-03-15 12:43:21 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 14, 2023):

I also found out that the description HTMLResponse data type is missing in generated swagger.json file:

    "ErrorResponse": {
      "description": "Error response"
    },
    "HTMLResponse": {
      "description": "HTML response"
    },

Because of this, the generator thinks that the response body should be empty. But that's not true.

I think specification should be like that:

    "ErrorResponse": {
      "description": "Error response"
    },
    "HTMLResponse": {
      "description": "HTML response",
      "schema": {
        "type": "string"
      }
    },

@swimmwatch commented on GitHub (Oct 14, 2023): I also found out that the description `HTMLResponse` data type is missing in generated `swagger.json` file: ```json "ErrorResponse": { "description": "Error response" }, "HTMLResponse": { "description": "HTML response" }, ``` Because of this, the generator thinks that the response body should be empty. But that's not true. I think specification should be like that: ```json "ErrorResponse": { "description": "Error response" }, "HTMLResponse": { "description": "HTML response", "schema": { "type": "string" } }, ```

kerem commented

2026-03-15 12:43:26 +03:00

Author

Owner

@axllent commented on GitHub (Oct 14, 2023):

I'll look into this soon, although I don't personally use swagger so I may require some help. I must admit that the bundled API documentation (which uses the swagger file) has been pretty great though.

@axllent commented on GitHub (Oct 14, 2023): I'll look into this soon, although I don't personally use swagger so I may require some help. I must admit that the bundled API documentation (which uses the swagger file) has been pretty great though.

kerem commented

2026-03-15 12:43:31 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 14, 2023):

Thanks, I will help as much as I can.

@swimmwatch commented on GitHub (Oct 14, 2023): Thanks, I will help as much as I can.

kerem commented

2026-03-15 12:43:36 +03:00

Author

Owner

@axllent commented on GitHub (Oct 15, 2023):

@swimmwatch I have made a number of changes which I believe fixes the errors and response data. Would you mind please checking out the feature/swagger branch and testing the swagger.json for me? Thanks

@axllent commented on GitHub (Oct 15, 2023): @swimmwatch I have made a number of changes which I believe fixes the errors and response data. Would you mind please checking out the `feature/swagger` branch and testing the [swagger.json](https://github.com/axllent/mailpit/blob/feature/swagger/server/ui/api/v1/swagger.json) for me? Thanks

kerem commented

2026-03-15 12:43:41 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 15, 2023):

Ok, I will check.

@swimmwatch commented on GitHub (Oct 15, 2023): Ok, I will check.

kerem commented

2026-03-15 12:43:46 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 15, 2023):

@adiabatic i have ran utility openapi-generator-cli with validate option:
Old specification:

swimmwatch@home-pc:~/Desktop/learn/mailpit-client$ docker run --rm -v "${PWD}":/local openapitools/openapi-generator-cli:v7.0.1 validate -i /local/swagger.json
Validating spec (/local/swagger.json)
Errors:
        - attribute paths.'/api/v1/messages'(put).[ids].description is unexpected
        - attribute paths.'/api/v1/search'(delete).operationId is repeated
        - attribute paths.'/api/v1/messages'(put).[ids].type is unexpected
        - attribute paths.'/api/v1/messages'(delete).[ids].type is unexpected
        - attribute paths.'/api/v1/tags'(put).[ids].type is unexpected
        - attribute paths.'/api/v1/message/{ID}/release'(post).[to].description is unexpected
        - attribute paths.'/api/v1/tags'(put).[ids].description is unexpected
        - attribute paths.'/api/v1/message/{ID}/release'(post).[to].type is unexpected
        - attribute paths.'/api/v1/messages'(delete).[ids].description is unexpected
        - attribute paths.'/api/v1/tags'(put).operationId is repeated

[error] Spec has 10 errors.

Fixed specification:

swimmwatch@home-pc:~/Desktop/learn/mailpit-client$ docker run --rm -v "${PWD}":/local openapitools/openapi-generator-cli:v7.0.1 validate -i /local/swagger_test.json
Validating spec (/local/swagger_test.json)
No validation issues detected.

All issues was fixed.

I have checked generated SDK:

GET /view/{ID}.html - Ok
GET /view/{ID}.txt - Ok

GET /api/v1/message/{ID}/part/{PartID} - Invalid data type for BinaryResponse: need specify that it is binary data.

"BinaryResponse": {
  "description": "Binary data response inherits the attachment's content type",
  "schema": {
    "type": "string",
    "format": "binary" // fix
  }
},

GET /api/v1/message/{ID}/headers - Ok
GET /api/v1/message/{ID} - Ok
GET /api/v1/message/{ID}/raw - Ok
GET /api/v1/message/{ID}/part/{PartID}/thumb - same problem as GET /api/v1/message/{ID}/part/{PartID}
POST /api/v1/message/{ID}/release - I don't understand what this method does. Can you explain please?
PUT /api/v1/tags - Ok.
GET /api/v1/tags - Ok.
GET /api/v1/messages - Ok
PUT /api/v1/messages - Ok
DELETE /api/v1/messages - Ok
DELETE /api/v1/search - Ok
GET /api/v1/search - Ok
GET /api/v1/info - Ok
GET /api/v1/webui - Ok
GET /api/v1/message/{ID}/link-check - Ok
GET /api/v1/message/{ID}/html-check - Ok

@swimmwatch commented on GitHub (Oct 15, 2023): @adiabatic i have ran utility `openapi-generator-cli` with `validate` option: **Old specification:** ```bash swimmwatch@home-pc:~/Desktop/learn/mailpit-client$ docker run --rm -v "${PWD}":/local openapitools/openapi-generator-cli:v7.0.1 validate -i /local/swagger.json Validating spec (/local/swagger.json) Errors: - attribute paths.'/api/v1/messages'(put).[ids].description is unexpected - attribute paths.'/api/v1/search'(delete).operationId is repeated - attribute paths.'/api/v1/messages'(put).[ids].type is unexpected - attribute paths.'/api/v1/messages'(delete).[ids].type is unexpected - attribute paths.'/api/v1/tags'(put).[ids].type is unexpected - attribute paths.'/api/v1/message/{ID}/release'(post).[to].description is unexpected - attribute paths.'/api/v1/tags'(put).[ids].description is unexpected - attribute paths.'/api/v1/message/{ID}/release'(post).[to].type is unexpected - attribute paths.'/api/v1/messages'(delete).[ids].description is unexpected - attribute paths.'/api/v1/tags'(put).operationId is repeated [error] Spec has 10 errors. ``` **Fixed specification:** ```bash swimmwatch@home-pc:~/Desktop/learn/mailpit-client$ docker run --rm -v "${PWD}":/local openapitools/openapi-generator-cli:v7.0.1 validate -i /local/swagger_test.json Validating spec (/local/swagger_test.json) No validation issues detected. ``` All issues was fixed. --- I have checked generated SDK: - [x] `GET /view/{ID}.html` - Ok - [x] `GET /view/{ID}.txt` - Ok - [x] `GET /api/v1/message/{ID}/part/{PartID}` - Invalid data type for `BinaryResponse`: need specify that it is binary data. ```json "BinaryResponse": { "description": "Binary data response inherits the attachment's content type", "schema": { "type": "string", "format": "binary" // fix } }, ``` - [x] `GET /api/v1/message/{ID}/headers` - Ok - [x] `GET /api/v1/message/{ID}` - Ok - [x] `GET /api/v1/message/{ID}/raw` - Ok - [x] `GET /api/v1/message/{ID}/part/{PartID}/thumb` - same problem as `GET /api/v1/message/{ID}/part/{PartID}` - [ ] `POST /api/v1/message/{ID}/release` - I don't understand what this method does. Can you explain please? - [x] `PUT /api/v1/tags` - Ok. - [x] `GET /api/v1/tags` - Ok. - [x] `GET /api/v1/messages` - Ok - [x] `PUT /api/v1/messages` - Ok - [x] `DELETE /api/v1/messages` - Ok - [x] `DELETE /api/v1/search` - Ok - [x] `GET /api/v1/search` - Ok - [x] `GET /api/v1/info` - Ok - [x] `GET /api/v1/webui` - Ok - [x] `GET /api/v1/message/{ID}/link-check` - Ok - [x] `GET /api/v1/message/{ID}/html-check` - Ok

kerem commented

2026-03-15 12:43:52 +03:00

Author

Owner

@axllent commented on GitHub (Oct 15, 2023):

Yay, thanks for releasing testing! I've also added a validation test to prevent this happening in future, and I will merge this in tomorrow (my time) and release a new version 👍

@axllent commented on GitHub (Oct 15, 2023): Yay, thanks for releasing testing! I've also added a validation test to prevent this happening in future, and I will merge this in tomorrow (my time) and release a new version :+1:

kerem commented

2026-03-15 12:43:57 +03:00

Author

Owner

@axllent commented on GitHub (Oct 16, 2023):

Sorry, I missed your questions...

The binary file - the closest I can get to this is documented here which isn't exactly what you're after, but I think the only solution available.

    "BinaryResponse": {
      "description": "Binary data response inherits the attachment's content type",
      "schema": {
        "$ref": "#/definitions/File"
      }
    },
...
    "File": {
      "type": "object",
      "title": "File represents an open file descriptor.",
      "x-go-package": "os"
    },

There does not appear to be any way to define "format": "binary". I've just made the change to the feature branch mentioned earlier (if you have time to test this within the next couple of hours?), however I need to get a new Mailpit release out soon to address another issue so if I don't hear from you then I will just include the changes so far (including the BinaryResponse) and we can come back to this later.

POST /api/v1/message/{ID}/release - this is documented in the API as "Release a message via a pre-configured external SMTP server. This is only enabled if message relaying has been configured." and relates to the (SMTP relay)[https://github.com/axllent/mailpit/wiki/SMTP-relay] functionality. It is only enabled if the SMTP relay is configured. Do you need any more information about this?

@axllent commented on GitHub (Oct 16, 2023): Sorry, I missed your questions... The binary file - the closest I can get to this is [documented here](https://goswagger.io/faq/faq_spec.html#how-to-define-a-swagger-response-that-produces-a-binary-file) which isn't exactly what you're after, but I think the only solution available. ``` "BinaryResponse": { "description": "Binary data response inherits the attachment's content type", "schema": { "$ref": "#/definitions/File" } }, ... "File": { "type": "object", "title": "File represents an open file descriptor.", "x-go-package": "os" }, ``` There does not appear to be any way to define `"format": "binary"`. I've just made the change to the feature branch mentioned earlier (if you have time to test [this](https://github.com/axllent/mailpit/blob/feature/swagger/server/ui/api/v1/swagger.json) within the next couple of hours?), however I need to get a new Mailpit release out soon to address another issue so if I don't hear from you then I will just include the changes so far (including the BinaryResponse) and we can come back to this later. `POST /api/v1/message/{ID}/release` - this is documented in the API as "Release a message via a pre-configured external SMTP server. This is only enabled if message relaying has been configured." and relates to the (SMTP relay)[https://github.com/axllent/mailpit/wiki/SMTP-relay] functionality. It is only enabled if the SMTP relay is configured. Do you need any more information about this?

kerem commented

2026-03-15 12:44:02 +03:00

Author

Owner

@axllent commented on GitHub (Oct 16, 2023):

The link I provided earlier won't work any more as this has now been merged into develop and released with v1.9.8. As I mentioned before, I'm not sure whether the BinaryResponse "solution" I provided actually helps or potentially makes things worse for you, but please let me know either way.

@axllent commented on GitHub (Oct 16, 2023): The link I provided earlier won't work any more as this has now been merged into `develop` and released with v1.9.8. As I mentioned before, I'm not sure whether the `BinaryResponse` "solution" I provided actually helps or potentially makes things worse for you, but please let me know either way.

kerem commented

2026-03-15 12:44:07 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 16, 2023):

@axllent sorry i couldn't answer because of work.

Unfortunately the latest version swagger.json doesn't work for BinaryResponse.

Can you please tell me how to generate the swagger file yourself? I want to try something from Google.

POST /api/v1/message/{ID}/release - Ok. Thanks.

@swimmwatch commented on GitHub (Oct 16, 2023): @axllent sorry i couldn't answer because of work. Unfortunately the latest version `swagger.json` doesn't work for `BinaryResponse`. Can you please tell me how to generate the swagger file yourself? I want to try something from Google. `POST /api/v1/message/{ID}/release` - Ok. Thanks.

kerem commented

2026-03-15 12:44:12 +03:00

Author

Owner

@axllent commented on GitHub (Oct 17, 2023):

I'll try keep this as simple as possible. I don't know what architecture or platform you're on, so I'll assume Linux amd64.
Here's the swagger binary (for go-swagger): swagger.tar.gz

From within the root directory of Mailpit:
./swagger generate spec -m -i ./server/apiv1/swagger-config.yml -o ./server/ui/api/v1/swagger.json

@axllent commented on GitHub (Oct 17, 2023): I'll try keep this as simple as possible. I don't know what architecture or platform you're on, so I'll assume Linux amd64. Here's the swagger binary (for go-swagger): [swagger.tar.gz](https://github.com/axllent/mailpit/files/12923720/swagger.tar.gz) From within the root directory of Mailpit: `./swagger generate spec -m -i ./server/apiv1/swagger-config.yml -o ./server/ui/api/v1/swagger.json`

kerem commented

2026-03-15 12:44:17 +03:00

Author

Owner

@axllent commented on GitHub (Oct 28, 2023):

Did you get anywhere with a potential solution for this @swimmwatch ?

@axllent commented on GitHub (Oct 28, 2023): Did you get anywhere with a potential solution for this @swimmwatch ?

kerem commented

2026-03-15 12:44:22 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 28, 2023):

@axllent hi!

Sorry for my delay.

I have run this program on my PC (Ubuntu 20.04):

swimmwatch@home-pc:~/Desktop/learn/mailpit$ ./swagger generate spec -m -i ./server/apiv1/swagger-config.yml -o ./server/ui/api/v1/swagger.json
./swagger: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.32' not found (required by ./swagger)
./swagger: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./swagger)

Can you send me command that uses Docker please?

@swimmwatch commented on GitHub (Oct 28, 2023): @axllent hi! Sorry for my delay. I have run this program on my PC (Ubuntu 20.04): ```bash swimmwatch@home-pc:~/Desktop/learn/mailpit$ ./swagger generate spec -m -i ./server/apiv1/swagger-config.yml -o ./server/ui/api/v1/swagger.json ./swagger: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.32' not found (required by ./swagger) ./swagger: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./swagger) ``` Can you send me command that uses Docker please?

kerem commented

2026-03-15 12:44:27 +03:00

Author

Owner

@axllent commented on GitHub (Oct 29, 2023):

@swimmwatch Sorry about that. I've created a very basic docker image which should work - unfortunately it's very slow as it takes about a minute here to generate the docs as it also needs to compile Mailpit in the background. The image is also pretty large as go-swagger requires go to be installed too.

You can run this within the project folder:

docker run --rm -it -u $(id -u):$(id -g) -v "$(pwd)":/source axllent/go-swagger generate spec -m -i ./server/apiv1/swagger config.yml -o ./server/ui/api/v1/swagger.json

@axllent commented on GitHub (Oct 29, 2023): @swimmwatch Sorry about that. I've created a very basic docker image which should work - unfortunately it's very slow as it takes about a minute here to generate the docs as it also needs to compile Mailpit in the background. The image is also pretty large as go-swagger requires go to be installed too. You can run this within the project folder: ```shell docker run --rm -it -u $(id -u):$(id -g) -v "$(pwd)":/source axllent/go-swagger generate spec -m -i ./server/apiv1/swagger config.yml -o ./server/ui/api/v1/swagger.json ```

kerem commented

2026-03-15 12:44:33 +03:00

Author

Owner

@swimmwatch commented on GitHub (Oct 29, 2023):

@axllent thank you for command!
Unfortunately, this command generates empty swagger.json file:

{
  "swagger": "2.0",
  "paths": {}
}

Can you please tell me what could be causing this? I have run this within the project folder.

@swimmwatch commented on GitHub (Oct 29, 2023): @axllent thank you for command! Unfortunately, this command generates empty `swagger.json` file: ```json { "swagger": "2.0", "paths": {} } ``` Can you please tell me what could be causing this? I have run this within the project folder.

kerem commented

2026-03-15 12:44:38 +03:00

Author

Owner

@axllent commented on GitHub (Oct 30, 2023):

Oh shit, I'm so sorry - there was a typo in my original command:

docker run --rm -it -u $(id -u):$(id -g) -v "$(pwd)":/source axllent/go-swagger generate spec -m -i ./server/apiv1/swagger-config.yml -o ./server/ui/api/v1/swagger.json

I had a space instead of a - in the swagger-config.yml part. This should definitely work now.

@axllent commented on GitHub (Oct 30, 2023): Oh shit, I'm so sorry - there was a typo in my original command: ```shell docker run --rm -it -u $(id -u):$(id -g) -v "$(pwd)":/source axllent/go-swagger generate spec -m -i ./server/apiv1/swagger-config.yml -o ./server/ui/api/v1/swagger.json ``` I had a space instead of a `-` in the `swagger-config.yml ` part. This should definitely work now.

kerem commented

2026-03-15 12:44:43 +03:00

Author

Owner

@swimmwatch commented on GitHub (Nov 5, 2023):

@axllent hi! Thanks for command fix. I have tried to generate properly swagger.json but unfortunately i can't find valid type for BinaryResponse.

I think this issue can be closed. The most important thing is that I wanted to suggest to use swagger validation. Thank you for help.

I hope that in the future I will be able to offer something useful for this project.

@swimmwatch commented on GitHub (Nov 5, 2023): @axllent hi! Thanks for command fix. I have tried to generate properly `swagger.json` but unfortunately i can't find valid type for `BinaryResponse`. I think this issue can be closed. The most important thing is that I wanted to suggest to use swagger validation. Thank you for help. I hope that in the future I will be able to offer something useful for this project.

kerem commented

2026-03-15 12:44:48 +03:00

Author

Owner

@axllent commented on GitHub (Nov 6, 2023):

@swimmwatch I feared that would be the case (that you also wouldn't find a solution to that). Considering this is the case, I think it may be better I change it back to "type": "string" for the sake of the API documentation as it also doesn't understand the "new format" (my attempt at making it binary as per the instructions I followed). What do you think, is the original string OK?

The upside is there is now automatic validation, so thanks for your suggestion and help there.

@axllent commented on GitHub (Nov 6, 2023): @swimmwatch I feared that would be the case (that you also wouldn't find a solution to that). Considering this is the case, I think it may be better I change it back to `"type": "string"` for the sake of the API documentation as it also doesn't understand the "new format" (my attempt at making it binary as per the instructions I followed). What do you think, is the original string OK? The upside is there is now automatic validation, so thanks for your suggestion and help there.

kerem referenced this issue

2026-03-15 14:19:38 +03:00

[PR #123] [MERGED] Fix: Add single dash arguments support to sendmail command #448

Rows
Columns

[GH-ISSUE #188] Swagger file #123