[OpenAPI] Add Swagger documentation for the RESTful API

[netsensei]

Story

I should be able to see a Swagger documentation when I navigate to /swagger/. The Swagger documentation allows me to interact with the REST API.

Success criteria

• [ ] I can see a page with Swagger documentation about the API when I navigate to /swagger/.
• [ ] I need to authorize with the X-API-key token before I can test the API via the Swagger documentation.

Implementation suggestion

First, copy the directory public/swagger-ui-5.1.0 from the OAI service to the public/ directory of the people service.

Next, check the public/swagger-ui-5.1.0/swagger/swagger-initializer.js file. The url property should point to the api/v1/openapi.yaml file. Ignore any and all comments in that file: this is part from a ZIP file downloaded from the Swagger website.

window.ui = SwaggerUIBundle({
    url: "../api/v1/openapi.yaml",
    ...
}

Next, hook up the swagger folder and it's code in the mux router in cmd/api.go like this:

// mount api
mux.Mount("/api/v1", http.StripPrefix("/api/v1", apiServer))
mux.Get("/api/v1/openapi.yaml", func(w http.ResponseWriter, r *http.Request) {
    http.ServeFile(w, r, "api/v1/openapi.yaml")
})
mux.Mount("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("public/swagger-ui-5.1.0"))))

When you navigate to /swagger/ path, you should see the documentation. Don't forget the trailing / at the end!

Automatic testing scenario

n/a

Related issues

• 18