[GH-ISSUE #65] OpenAPI / Swagger schema

kerem commented

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

Owner

Originally created by @PaoloC68 on GitHub (Mar 13, 2023).
Original GitHub issue: https://github.com/axllent/mailpit/issues/65

One of the reason for which I arrived to this project is because I was frustrated by the fact that after having built a client for Mailhog based on the schema file I had to discover that the provided schema was in no way matching the reality, making me just waste time.
I am not a go programmer, I mostly use Python and Django and as such I find very convenient the automated schema generation. It seems that there is something similar for Go projects that generates the schema parsing the code as explained here.
Maybe somebody can take a look. It would help a lot such schema so automatically could be generated API clients for MailPit in the most wide range of programming languages.
Here an example on how to comment the code so that the schema can be generated and kept in sync with the code.

Originally created by @PaoloC68 on GitHub (Mar 13, 2023). Original GitHub issue: https://github.com/axllent/mailpit/issues/65 One of the reason for which I arrived to this project is because I was frustrated by the fact that after having built a client for Mailhog based on the schema file I had to discover that the provided schema was in no way matching the reality, making me just waste time. I am not a go programmer, I mostly use Python and Django and as such I find very convenient the automated schema generation. It seems that there is something similar for Go projects that generates the schema parsing the code as explained [here](https://goswagger.io/use/spec.html#swaggerjson-generation). Maybe somebody can take a look. It would help a lot such schema so automatically could be generated API clients for MailPit in the most wide range of programming languages. [Here](https://goswagger.io/use/spec/route.html#example) an example on how to comment the code so that the schema can be generated and kept in sync with the code.

kerem

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

closed this issue
added the
enhancement
label

kerem commented

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

Author

Owner

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

Hi. Does the existing API documentation not provide you with the information you require? I realize that you would prefer something you can import to save you time, however a) that would take me hours to learn, b) take me hours to create, and c) I don't use swagger so I could not test / verify it.

I welcome a PR from anyone with knowledge of swagger who is willing to spend a lot of time (re)documenting inline all the methods and responses, but I won't be writing it myself, sorry.

@axllent commented on GitHub (Mar 14, 2023): Hi. Does the [existing API documentation](https://github.com/axllent/mailpit/tree/develop/docs/apiv1) not provide you with the information you require? I realize that you would prefer something you can import to save **you** time, however a) that would take me hours to learn, b) take me hours to create, and c) I don't use swagger so I could not test / verify it. I welcome a PR from anyone with knowledge of swagger who is willing to spend a lot of time (re)documenting inline all the methods and responses, but I won't be writing it myself, sorry.

kerem commented

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

Author

Owner

@PaoloC68 commented on GitHub (Mar 14, 2023):

I totally understand your point, as you know in our area you never stop to learn.
As a fellow programmer I strongly recommend you to have a look into the OpenAPI specs which are also followed by swagger.
Allow me to quote the brief description of what are the OpenAPI Specifications:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

I think that is fair to say that nowadays every project that exposes an API should expose an OpenAPI schema. I understand that you may not have time at the moment, just keep it in mind whenever it happens to you to do some API work.

I hope that you don't take that as a critique but is just a friendly and respectful suggestion.

Cheers!

@PaoloC68 commented on GitHub (Mar 14, 2023): I totally understand your point, as you know in our area you never stop to learn. As a fellow programmer I strongly recommend you to have a look into the OpenAPI specs which are also followed by [swagger](https://swagger.io/specification/). Allow me to quote the brief description of what are the [OpenAPI Specifications](https://spec.openapis.org/oas/v3.1.0): > The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service. I think that is fair to say that nowadays every project that exposes an API should expose an OpenAPI schema. I understand that you may not have time at the moment, just keep it in mind whenever it happens to you to do some API work. I hope that you don't take that as a critique but is just a friendly and respectful suggestion. Cheers!

kerem commented

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

Author

Owner

@axllent commented on GitHub (Mar 19, 2023):

Thank you for your input. As I expected, it has taken me several (far more than I'd like to admit) hours to try understand and generate the swagger JSON & yaml configs (not yet committed to git), but I need some input before I push my changes. Given your request for this, I assume you use swagger often, and so you should be able to answer the following questions I have:

How is a swagger config file supposed to be accessed / loaded? Is it simply accessed via a Github repo, or should it be accessed via the Mailpit server (eg: http://localhost:8025/swagger.json)?

Is there a default location within a repository for the swagger configs?

Although I am able to generate a config of all API routes and models (using go-swagger / inline comments), which can be parsed without errors using the official swagger-editor, I must admit that the built in swagger-editor's "generate client" (Swagger Codegen) functionality produces a lot more code than I was expecting, but maybe that's the side-effect of a one-show-fits-all solution like swagger. Your mileage may vary of course, and who knows, maybe this is expected.... With this said, once I can get a better understanding of where I'm supposed to put the configs, I'm likely going to need you to do some testing and provide feedback before any of this makes it way into production.

So if you can please give me some info re: my questions above that would be great, thank you.

@axllent commented on GitHub (Mar 19, 2023): Thank you for your input. As I expected, it has taken me several (far more than I'd like to admit) hours to try understand and generate the swagger JSON & yaml configs (not yet committed to git), but I need some input before I push my changes. Given your request for this, I assume you use swagger often, and so you should be able to answer the following questions I have: How is a swagger config file supposed to be accessed / loaded? Is it simply accessed via a Github repo, or should it be accessed via the Mailpit server (eg: `http://localhost:8025/swagger.json`)? Is there a default location within a repository for the swagger configs? Although I am able to generate a config of all API routes and models (using go-swagger / inline comments), which can be parsed without errors using the official swagger-editor, I must admit that the built in swagger-editor's "generate client" (Swagger Codegen) functionality produces a **lot** more code than I was expecting, but maybe that's the side-effect of a one-show-fits-all solution like swagger. Your mileage may vary of course, and who knows, maybe this is expected.... With this said, once I can get a better understanding of where I'm supposed to put the configs, I'm likely going to need you to do some testing and provide feedback before any of this makes it way into production. So if you can please give me some info re: my questions above that would be great, thank you.

kerem commented

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

Author

Owner

@axllent commented on GitHub (Mar 25, 2023):

@PaoloC68 Would you mind please getting back to me on my previous questions? Thank you.

@axllent commented on GitHub (Mar 25, 2023): @PaoloC68 Would you mind please getting back to me on my previous questions? Thank you.

kerem commented

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

Author

Owner

@nosovk commented on GitHub (Mar 29, 2023):

Unfortunately "generate client" is almost never used, but in common swagger is a good way to document your's API.
You can get something like https://rapidocweb.com/ and get https://app.mailcheck.co/docs in 10 lines of code

@nosovk commented on GitHub (Mar 29, 2023): Unfortunately "generate client" is almost never used, but in common swagger is a good way to document your's API. You can get something like https://rapidocweb.com/ and get https://app.mailcheck.co/docs in 10 lines of code

kerem commented

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

Author

Owner

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

Thanks @nosovk . I guess what has me most confused at this point is that these Swagger web UIs have a "try" button, however Mailpit is presumably (but not necessarily) running local. Does this mean that the swagger.json file should be included in the HTTP server and accessed via (for example) http://localhost:8025/swagger.json, or are they simply loaded by a developer regardless where in the source code the swagger.json is located, and developers don't usually use the "try" feature because it doesn't work most of the time?

You see, I just don't know what "swagger users" expect exactly. Sure I can create a swagger.json, but if it isn't implemented in a useful manner then there is no point. I am just trying to get some clarity (some of which you already provided, so thank you).

@axllent commented on GitHub (Mar 29, 2023): Thanks @nosovk . I guess what has me most confused at this point is that these Swagger web UIs have a "try" button, however Mailpit is presumably (but not necessarily) running local. Does this mean that the swagger.json file should be included in the HTTP server and accessed via (for example) `http://localhost:8025/swagger.json`, or are they simply loaded by a developer regardless where in the source code the swagger.json is located, and developers don't usually use the "try" feature because it doesn't work most of the time? You see, I just don't know what "swagger users" expect exactly. Sure I can create a swagger.json, but if it isn't implemented in a useful manner then there is no point. I am just trying to get some clarity (some of which you already provided, so thank you).

kerem commented

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

Author

Owner

@nosovk commented on GitHub (Mar 29, 2023):

You are correct when say that swagger.json should be served as a static file from an included HTTP server. In most cases we expect good documentation with examples (is you use open API v3 there could be some examples inside doc, like typical request\response etc).
Good reference is a doc link I mentioned before. There are static openapi.json and nice web ui to read it.

@nosovk commented on GitHub (Mar 29, 2023): You are correct when say that swagger.json should be served as a static file from an included HTTP server. In most cases we expect good documentation with examples (is you use open API v3 there could be some examples inside doc, like typical request\response etc). Good reference is a doc link I mentioned before. There are static openapi.json and nice web ui to read it.

kerem commented

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

Author

Owner

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

I'm afraid to say it, but I'm still quite lost as to "what next". I am currently using go-swagger locally to generate a Swagger 2 / OpenAPI 2.0 file - that appears to work fine, and outputs a valid swagger.json (and yml) file based off code comments I have in my local branch. I can then open that physical spec file successfully via swagger-editor (using their Docker image), and that results in the following:

It contains the methods, the required and optional parameters, and expected response structures.

I have then tried serving the swagger.json via the Mailpit HTTP server, and I can access that file via my browser without issues, however I cannot seem to load it successfully via any of the tools (that I have tried) because that appears to expect the http server to be publicly available (internet) which it obviously isn't. I also can't "test" ("try") the API via swagger-editor because it keeps trying "localhost" on the same port as the swagger-editor is running. If I try load http://:8025/swagger.json` using swagger-editor (or swagger-ui) I get generic errors.

So I have generated the schema, but I am really not sure what to do now, if anything. I guess my question is, do I really need to do anything? As I mentioned in previous messages here, I do not use swagger myself (nor do I plan to), so this is new to me. I am just trying to satisfy users such as yourselves by providing documentation as to how to use the API (ie: swagger), but I feel I'm either missing something, or there is now a lot more I need to do in order for anyone to actually use this.

I have the spec json/yaml file, it can be served via the Mailpit server - what now? I am not looking to create more work for myself, but I'd like this to usable by developers such as yourself (else all the hours I have put in was all for nothing).

@axllent commented on GitHub (Mar 30, 2023): I'm afraid to say it, but I'm still quite lost as to "what next". I am currently using [go-swagger](https://goswagger.io) locally to generate a Swagger 2 / OpenAPI 2.0 file - that appears to work fine, and outputs a valid swagger.json (and yml) file based off code comments I have in my local branch. I can then open that physical spec file successfully via swagger-editor (using their [Docker image](https://hub.docker.com/r/swaggerapi/swagger-editor)), and that results in the following: ![Swagger-Editor](https://user-images.githubusercontent.com/1463435/228727637-11a97a4b-5073-41e8-8351-5e75c4c64ae0.png) It contains the methods, the required and optional parameters, and expected response structures. I have then tried serving the swagger.json via the Mailpit HTTP server, and I can access that file via my browser without issues, however I cannot seem to load it successfully via any of the tools (that I have tried) because that appears to expect the http server to be publicly available (internet) which it obviously isn't. I also can't "test" ("try") the API via swagger-editor because it keeps trying "localhost" on the same port as the swagger-editor is running. If I try load http://<my-ip>:8025/swagger.json` using swagger-editor (or swagger-ui) I get generic errors. So I have generated the schema, but I am really not sure what to do now, if anything. I guess my question is, do I really need to do anything? As I mentioned in previous messages here, I do not use swagger myself (nor do I plan to), so this is new to me. I am just trying to satisfy users such as yourselves by providing documentation as to how to use the API (ie: swagger), but I feel I'm either missing something, or there is now a lot more I need to do in order for anyone to actually use this. I have the spec json/yaml file, it can be served via the Mailpit server - what now? I am not looking to create more work for myself, but I'd like this to usable by developers such as yourself (else all the hours I have put in was all for nothing).

kerem commented

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

Author

Owner

@nosovk commented on GitHub (Mar 30, 2023):

Try to add something like that doc.html into server near the swagger.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes"
    />
    <style>
      rapi-doc {
        width: 100%;
      }
      img {
        width: 127px;
      }
    </style>
    <script
      type="text/javascript"
      src="https://unpkg.com/rapidoc@8.4.2/dist/rapidoc-min.js"
    ></script>
  </head>
  <body>
 <rapi-doc
          id="thedoc"
          spec-url="/swagger.json"
          theme="light"
          layout="column"
          render-style="read"
          allow-spec-url-load="false"
          allow-spec-file-load="false"
          allow-server-selection="false"
          allow-search="false"
          bg-color="#f0f3f6"
          nav-bg-color="#e3e8ec"
          nav-text-color="#999"
          nav-hover-bg-color="#fff"
          header-color="#e3e8ec"
          primary-color="#553adf"
          text-color="#4d4d4d"
          regular-font="'Arial', sans-serif"
          mono-font="Inconsolata,Monaco,Consolas,'Courier New',Courier,monospace"
        >
          <div slot="header">Mailpit API documentation</div>
          <a target='_blank' href="/" slot="logo">
            <img src="/ui/mailpit.svg"
          /></a>
        </rapi-doc>`;
  </body>
</html>

You may see that it will consume /swagger.json from local go http server

@nosovk commented on GitHub (Mar 30, 2023): Try to add something like that doc.html into server near the swagger. ```html <!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes" /> <style> rapi-doc { width: 100%; } img { width: 127px; } </style> <script type="text/javascript" src="https://unpkg.com/rapidoc@8.4.2/dist/rapidoc-min.js" ></script> </head> <body> <rapi-doc id="thedoc" spec-url="/swagger.json" theme="light" layout="column" render-style="read" allow-spec-url-load="false" allow-spec-file-load="false" allow-server-selection="false" allow-search="false" bg-color="#f0f3f6" nav-bg-color="#e3e8ec" nav-text-color="#999" nav-hover-bg-color="#fff" header-color="#e3e8ec" primary-color="#553adf" text-color="#4d4d4d" regular-font="'Arial', sans-serif" mono-font="Inconsolata,Monaco,Consolas,'Courier New',Courier,monospace" > <div slot="header">Mailpit API documentation</div> <a target='_blank' href="/" slot="logo"> <img src="/ui/mailpit.svg" /></a> </rapi-doc>`; </body> </html> ``` You may see that it will consume /swagger.json from local go http server

kerem commented

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

Author

Owner

@axllent commented on GitHub (Mar 31, 2023):

@nosovk thank you so much, this helps more than you can imagine! I have it working very nicely via the base of the API route (http://0.0.0.0:8025/api/v1/), and it is able to "try" all the endpoints successfully (provided they can valid parameters of course). This is awesome, thank you for your help. I will release a new version soon that will include this.

@axllent commented on GitHub (Mar 31, 2023): @nosovk thank you so much, this helps more than you can imagine! I have it working very nicely via the base of the API route (`http://0.0.0.0:8025/api/v1/`), and it is able to "try" all the endpoints successfully (provided they can valid parameters of course). This is awesome, thank you for your help. I will release a new version soon that will include this.

kerem commented

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

Author

Owner

@axllent commented on GitHub (Mar 31, 2023):

Swagger / OpenAPI documentation has now been released as part of v1.5.0. Please give it a test and let me know if this is suitable? Thank you.

@axllent commented on GitHub (Mar 31, 2023): Swagger / OpenAPI documentation has now been released as part of v1.5.0. Please give it a test and let me know if this is suitable? Thank you.

kerem commented

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

Author

Owner

@PaoloC68 commented on GitHub (Apr 2, 2023):

@axllent Sorry for not getting back ton you earlier, I was really busy, I appreciate the effort you have done and as soon as tt will fit in my schedule I will give a try!
Thank you!

@PaoloC68 commented on GitHub (Apr 2, 2023): @axllent Sorry for not getting back ton you earlier, I was really busy, I appreciate the effort you have done and as soon as tt will fit in my schedule I will give a try! Thank you!

kerem commented

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

Author

Owner

@axllent commented on GitHub (Apr 21, 2023):

I'm closing this issue as it has been three weeks since the swagger documentation was released.

@axllent commented on GitHub (Apr 21, 2023): I'm closing this issue as it has been three weeks since the swagger documentation was released.

Rows
Columns

[GH-ISSUE #65] OpenAPI / Swagger schema #40