How to Provide a Swagger UI Interface in Plain HTML That Works

Swagger UI is only one of the solutions available for providing functional documentation for your APIs, but it is perhaps the most popular. Based on the OpenAPI specification, it’s more than just a document to read: it allows you to try your requests and get sample responses.

I often have to provide APIs at work. Most of the time, I’m the only one who use them, so I don’t need to share documents about how they work. But sometimes I do, because the same endpoint would be used by other vendors or customers, then I would fill out a sort of simple text document.

This can be enough, since experienced developers don’t need lots of details to call an API, but let me say that it’s not that professional. A faster way to provide a better documentation is Postman: a de facto standard for sharing APIs configurations. Anyway, although it support the same specification, it’s a commercial product.

I think the most efficient way of providing APIs documentation is still Swagger UI. I thought it required more resources that it actually does: in fact, you can create a working HTML page in a while. You don’t even need to download and host external dependencies.

Using assets hosted by cdnjs, you can easily build a Swagger UI web page and make it accessible to your colleagues: it doesn’t require any server-side tool. It will turn your JSON or YAML specification in an interactive user interface that automatically structures your documentation.

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.0/swagger-ui.min.css" integrity="sha512-QIJpSy6rqOKoEjIR+Pp7r5lTkNPJPJCRejWzG4jb12bCT1EeL/vcjZtk4NNKeEuVRXY+d34d/t9y1CHzZbgeJQ==" crossorigin="anonymous" referrerpolicy="no-referrer">

<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.29.0/swagger-ui-bundle.min.js" integrity="sha512-uRL0dWo7kTNu+5ZwjyjVBt1Seg5JM14NX0Yo3nToKUVJPLINpNYvFrOYQq2ALBxRMCSMT4vSAexXYDUp5Qbt/A==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

You need only two files to get started: a CSS file, and a JavaScript file. Swagger UI is also provided in three different npm packages, but I think I will speak about them another time. Once you set these either inside your page head or before the end of your page body, you can go on with the HTML markup.

<div id="swagger-ui"></div>

It doesn’t really matter the ID of your choice: it will be immediately called by your custom script below, so of course they must match, but you can give it the name you want. When you’re done, you can specify your settings and an OpenAPI-compatible specification.

<script>

  window.onload = () => {

    window.ui = SwaggerUIBundle({

      url: 'https://petstore3.swagger.io/api/v3/openapi.json',

      dom_id: '#swagger-ui',

    });

  };

</script>

I set the URL of the official example to let you see a working result, but you should replace it with your own. I opted for a YAML-formatted document, since it seems to be the OpenAPI preferred format: SwaggerUIBundle controls every element of the page you may want to show and/or hide.

You can find the full list of parameters in the official documentation. Although they are very important, since they let you customize the whole experience, you should pay more attention to the CORS issues: if your APIs are correctly configured, then you will succeed in letting your colleagues actually try them.

Swagger UI uses fetch() to make requests to the endpoint set on you specification: this means that you should care a lot about what you put in it. In my case I had a public API to document, so it didn’t require any kind of authentication, but you could have to add it.

It supports OAuth 2.0 out of the box, and offers some parameters to handle it, but you can also use an api-key header instead. Apart from the CORS, what impressed me is that you don’t need a running server behind: well, the API itself do, but Swagger UI doesn’t.

I want to go further and having an even more customizable version to manage with Vite and Rolldown, but this solution was fine for my purpose. I had some issues with the OpenAPI v3.x specification to get routes working, but they are not related with Swagger UI: I must study it better.