Skip to content

Make Your Own swagger-4-es⚓︎

You may consider customising the swagger-4-es openapi specification (e.g. additional endpoints, payloads and notes) to become a training resource specific to your organisation.

Why would you want to setup your own Swagger Page to Elasticsearch:

  • Documenting the key endpoints saves a lot of google searching for precise parameters and lets you annotate specific end points (e.g. issues in dev/test check to see if the cluster has gone read-only due to space constraints).

  • It's also much more precise and faster to go to a Swagger UI page and hit try it out and select a preconfigured payload from a list, than go into dev tools in kibana and write out a payload. Noting you still have a lot of power and flexibility to fiddle with the request payloads when you need to.

  • It allows you to build automated tests again the openapi specification using tools like schemathesis. So when you want to upgrade elasticsearch you can test the APIs and your configuration are performing the way you expect. The openapi specification can be used to drive your tests by having endpoints that create indexes with data and then query that data.

  • It allows you to create mock elasticsearch enpoints for frontend development with tools such as postman.co or openapi-mock.

How to Create Your Own Swagger UI page for Elasticsearch/Opensearch⚓︎

The way to set this up fo yourself is very straight forward:

  1. Document your schema as a openapi.json file - Swagger Hub can help with this. You can download the swagger-4-es openapi.json here
  2. Copy the dist folder from the Swagger UI github page.
  3. Drop in your openapi.json from step one into the same folder as the HTML index file.
  4. change the url parameter in the index.html to "./openapi.json". so it looks like this :
const ui = SwaggerUIBundle({
  url: "./openapi.json",
  dom_id: "#swagger-ui",
  defaultModelsExpandDepth: -1,
  defaultModelExpandDepth: -1,
  docExpansion: "none",
  displayRequestDuration: true,
  useUnsafeMarkdown: true,
  deepLinking: true,
  presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
  plugins: [SwaggerUIBundle.plugins.DownloadUrl],
  layout: "StandaloneLayout",
});

It's also possible to include the openapi schema directly in the index.html file. To do this replace the url parameter with the spec parameter and make it equal the openapi schema.