API: Generate Go and HTML from swagger.json #2132

Signed-off-by: Michael Mayer <michael@photoprism.app>

Makefile

@@ -101,6 +101,10 @@ swag:
 swag-fmt:
 	@echo "Formatting Swagger API documentation..."
 	swag fmt --dir internal/api
+swag-go:
+	docker run --rm --pull always -v ./assets/docs:/assets/docs swaggerapi/swagger-codegen-cli generate -i /assets/docs/api/v1/swagger.json -l go -o /assets/docs/api/v1/go
+swag-html:
+	docker run --rm --pull always -v ./assets/docs:/assets/docs swaggerapi/swagger-codegen-cli generate -i /assets/docs/api/v1/swagger.json -l html2 -o /assets/docs/api/v1/html
 notice:
 	@echo "Creating license report for Go dependencies..."
 	go-licenses report ./internal/... ./pkg/... --template=.report.tmpl > NOTICE

internal/api/albums.go

@@ -36,7 +36,8 @@ func SaveAlbumYaml(album entity.Album) {
 
 // GetAlbum returns album details as JSON.
 //
-//	@Summary	get album details
+//	@Summary	returns album details as JSON
+//	@Id			GetAlbum
 //	@Tags		Albums
 //	@Produce	json
 //	@Success	200	{object}	entity.Album

internal/api/api.go

@@ -43,7 +43,7 @@ import (
 
 //	@title						PhotoPrism API
 //	@description				API request bodies and responses are usually JSON-encoded, except for binary data and some of the OAuth2 endpoints. Note that the `Content-Type` header must be set to `application/json` for this, as the request may otherwise fail with error 400.
-//  @description				When clients have a valid access token, e.g. obtained through the `POST /api/v1/session` or `POST /api/v1/oauth/token` endpoint, they can use a standard Bearer Authorization header to authenticate their requests. Submitting the access token with a custom `X-Auth-Token` header is supported as well.
+//	@description				When clients have a valid access token, e.g. obtained through the `POST /api/v1/session` or `POST /api/v1/oauth/token` endpoint, they can use a standard Bearer Authorization header to authenticate their requests. Submitting the access token with a custom `X-Auth-Token` header is supported as well.
 //	@externalDocs.description	Learn more ›
 //	@externalDocs.url			https://docs.photoprism.app/developer-guide/api/
 //	@version					v1

internal/api/photos.go

@@ -37,7 +37,8 @@ func SaveSidecarYaml(photo *entity.Photo) {
 
 // GetPhoto returns photo details as JSON.
 //
-//	@Summary	get photo details
+//	@Summary	returns photo details as JSON
+//	@Id			GetPhoto
 //	@Tags		Photos
 //	@Produce	json
 //	@Success	200	{object}	entity.Photo