📖 Improve API documentation (#545)

This PR represents a first step towards improving our automatically generated API documentation. It includes the following changes: * Adds general API level doc comments that are a requirement for Swagger/OpenAPI. * Adds missing godocs for parameters where they were missing. This was causing Swagger validation to fail and was preventing QE from successfully converting our Swagger 2 documentation to OpenAPI 3.0 * Fixes some incorrect parameter documentation * Adds a new target to convert our Swagger 2 documentation to OpenAPI 3.0 using the Swagger conversion API at `converter.swagger.io`. * Corrects the existing docs-swagger target command invocation. * Updates the redoc target to use the newly generated OpenAPI 3.0 documentation. --------- Signed-off-by: Sam Lucidi <[email protected]>
konveyor · Oct 27, 2023 · 4721a39 · 4721a39
1 parent 4d5196c
commit 4721a39
Show file tree

Hide file tree

Showing 34 changed files with 9,120 additions and 688 deletions.
diff --git a/Makefile b/Makefile
@@ -82,15 +82,19 @@ controller-gen:
 addon: fmt vet
 	go build -o bin/addon github.com/konveyor/tackle2-hub/hack/cmd/addon
 
-docs: docs-swagger docs-binding
+docs: docs-html docs-openapi3 docs-binding
 
 # Build Swagger API spec into ./docs directory
 docs-swagger:
-	${GOBIN}/swag init -g api/base.go
+	${GOBIN}/swag init -g pkg.go --dir api,assessment
+
+# Build OpenAPI 3.0 docs
+docs-openapi3: docs-swagger
+	curl -X POST -H "Content-Type: application/json" -d @docs/swagger.json https://converter.swagger.io/api/convert | jq > docs/openapi3.json
 
 # Build HTML docs from Swagger API spec
-docs-html: docs-swagger
-	redoc-cli bundle -o docs/index.html docs/swagger.json
+docs-html: docs-openapi3
+	redoc-cli bundle -o docs/index.html docs/openapi3.json
 
 # Build binding doc.
 docs-binding:

diff --git a/api/adoptionplan.go b/api/adoptionplan.go
@@ -37,14 +37,14 @@ func (h AdoptionPlanHandler) AddRoutes(e *gin.Engine) {
 	routeGroup.POST(AdoptionPlansRoot, h.Graph)
 }
 
-// Get godoc
+// Graph godoc
 // @summary Generate an application dependency graph arranged in topological order.
 // @description Graph generates an application dependency graph arranged in topological order.
 // @tags adoptionplans
 // @produce json
-// @success 200 {object} api.DependencyGraph
+// @success 200 {object} []api.Vertex
 // @router /adoptionplans [post]
-// @param requestedApps path array true "requested App IDs"
+// @param requestedApps body []uint true "List of requested App IDs"
 func (h AdoptionPlanHandler) Graph(ctx *gin.Context) {
 	var requestedApps []struct {
 		ApplicationID uint `json:"applicationId"`

diff --git a/api/analysis.go b/api/analysis.go
@@ -95,7 +95,7 @@ func (h AnalysisHandler) AddRoutes(e *gin.Engine) {
 // @produce octet-stream
 // @success 200 {object} api.Analysis
 // @router /analyses/{id} [get]
-// @param id path string true "Analysis ID"
+// @param id path int true "Analysis ID"
 func (h AnalysisHandler) Get(ctx *gin.Context) {
 	id := h.pk(ctx)
 	writer := AnalysisWriter{ctx: ctx}
@@ -118,7 +118,7 @@ func (h AnalysisHandler) Get(ctx *gin.Context) {
 // @produce octet-stream
 // @success 200 {object} api.Analysis
 // @router /applications/{id}/analysis [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 func (h AnalysisHandler) AppLatest(ctx *gin.Context) {
 	id := h.pk(ctx)
 	m := &model.Analysis{}
@@ -149,7 +149,7 @@ func (h AnalysisHandler) AppLatest(ctx *gin.Context) {
 // @produce octet-stream
 // @success 200
 // @router /applications/{id}/analysis/report [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 func (h AnalysisHandler) AppLatestReport(ctx *gin.Context) {
 	id := h.pk(ctx)
 	m := &model.Analysis{}
@@ -229,6 +229,7 @@ func (h AnalysisHandler) AppList(ctx *gin.Context) {
 // @produce json
 // @success 201 {object} api.Analysis
 // @router /application/{id}/analyses [post]
+// @param id path int true "Application ID"
 func (h AnalysisHandler) AppCreate(ctx *gin.Context) {
 	id := h.pk(ctx)
 	result := h.DB(ctx).First(&model.Application{}, id)
@@ -398,7 +399,7 @@ func (h AnalysisHandler) AppCreate(ctx *gin.Context) {
 // @tags analyses
 // @success 204
 // @router /analyses/{id} [delete]
-// @param id path string true "Analysis ID"
+// @param id path int true "Analysis ID"
 func (h AnalysisHandler) Delete(ctx *gin.Context) {
 	id := h.pk(ctx)
 	r := &model.Analysis{}
@@ -429,7 +430,7 @@ func (h AnalysisHandler) Delete(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} []api.TechDependency
 // @router /application/{id}/analysis/dependencies [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 func (h AnalysisHandler) AppDeps(ctx *gin.Context) {
 	resources := []TechDependency{}
 	// Latest
@@ -511,7 +512,7 @@ func (h AnalysisHandler) AppDeps(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} []api.Issue
 // @router /application/{id}/analysis/issues [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 func (h AnalysisHandler) AppIssues(ctx *gin.Context) {
 	resources := []Issue{}
 	// Latest
@@ -673,6 +674,7 @@ func (h AnalysisHandler) Issues(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} api.Issue
 // @router /analyses/issues/{id} [get]
+// @param id path int true "Issue ID"
 func (h AnalysisHandler) Issue(ctx *gin.Context) {
 	id := h.pk(ctx)
 	m := &model.Issue{}
@@ -698,6 +700,7 @@ func (h AnalysisHandler) Issue(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} []api.Incident
 // @router /analyses/issues/{id}/incidents [get]
+// @param id path int true "Issue ID"
 func (h AnalysisHandler) Incidents(ctx *gin.Context) {
 	issueId := ctx.Param(ID)
 	// Filter
@@ -900,7 +903,7 @@ func (h AnalysisHandler) RuleReports(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} []api.IssueReport
 // @router /analyses/report/applications/{id}/issues [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 func (h AnalysisHandler) AppIssueReports(ctx *gin.Context) {
 	resources := []*IssueReport{}
 	type M struct {
@@ -1176,6 +1179,7 @@ func (h AnalysisHandler) IssueAppReports(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} []api.FileReport
 // @router /analyses/report/issues/{id}/files [get]
+// @param id path int true "Issue ID"
 func (h AnalysisHandler) FileReports(ctx *gin.Context) {
 	resources := []FileReport{}
 	type M struct {

diff --git a/api/application.go b/api/application.go
@@ -388,7 +388,8 @@ func (h ApplicationHandler) Update(ctx *gin.Context) {
 // @produce octet-stream
 // @success 200
 // @router /applications/{id}/bucket/{wildcard} [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
+// @param wildcard path string true "Content path"
 // @param filter query string false "Filter"
 func (h ApplicationHandler) BucketGet(ctx *gin.Context) {
 	m := &model.Application{}
@@ -413,7 +414,8 @@ func (h ApplicationHandler) BucketGet(ctx *gin.Context) {
 // @produce json
 // @success 204
 // @router /applications/{id}/bucket/{wildcard} [post]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
+// @param wildcard path string true "Content path"
 func (h ApplicationHandler) BucketPut(ctx *gin.Context) {
 	m := &model.Application{}
 	id := h.pk(ctx)
@@ -437,7 +439,8 @@ func (h ApplicationHandler) BucketPut(ctx *gin.Context) {
 // @produce json
 // @success 204
 // @router /applications/{id}/bucket/{wildcard} [delete]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
+// @param wildcard path string true "Content path"
 func (h ApplicationHandler) BucketDelete(ctx *gin.Context) {
 	m := &model.Application{}
 	id := h.pk(ctx)
@@ -461,7 +464,7 @@ func (h ApplicationHandler) BucketDelete(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} []api.Ref
 // @router /applications/{id}/tags [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 func (h ApplicationHandler) TagList(ctx *gin.Context) {
 	id := h.pk(ctx)
 	app := &model.Application{}
@@ -533,6 +536,7 @@ func (h ApplicationHandler) TagList(ctx *gin.Context) {
 // @success 201 {object} api.Ref
 // @router /applications/{id}/tags [post]
 // @param tag body Ref true "Tag data"
+// @param id path int true "Application ID"
 func (h ApplicationHandler) TagAdd(ctx *gin.Context) {
 	id := h.pk(ctx)
 	ref := &TagRef{}
@@ -572,7 +576,7 @@ func (h ApplicationHandler) TagAdd(ctx *gin.Context) {
 // @accept json
 // @success 204
 // @router /applications/{id}/tags [patch]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param source query string false "Source"
 // @param tags body []TagRef true "Tag references"
 func (h ApplicationHandler) TagReplace(ctx *gin.Context) {
@@ -626,7 +630,7 @@ func (h ApplicationHandler) TagReplace(ctx *gin.Context) {
 // @tags applications
 // @success 204
 // @router /applications/{id}/tags/{sid} [delete]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param sid path string true "Tag ID"
 func (h ApplicationHandler) TagDelete(ctx *gin.Context) {
 	id := h.pk(ctx)
@@ -661,7 +665,7 @@ func (h ApplicationHandler) TagDelete(ctx *gin.Context) {
 // @produce json
 // @success 200 {object} api.FactMap
 // @router /applications/{id}/facts/{source}: [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param source path string true "Source key"
 func (h ApplicationHandler) FactList(ctx *gin.Context, key FactKey) {
 	id := h.pk(ctx)
@@ -693,7 +697,7 @@ func (h ApplicationHandler) FactList(ctx *gin.Context, key FactKey) {
 // @produce json
 // @success 200 {object} object
 // @router /applications/{id}/facts/{key} [get]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param key path string true "Fact key"
 func (h ApplicationHandler) FactGet(ctx *gin.Context) {
 	id := h.pk(ctx)
@@ -738,7 +742,7 @@ func (h ApplicationHandler) FactGet(ctx *gin.Context) {
 // @produce json
 // @success 201
 // @router /applications/{id}/facts [post]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param fact body api.Fact true "Fact data"
 func (h ApplicationHandler) FactCreate(ctx *gin.Context) {
 	id := h.pk(ctx)
@@ -775,7 +779,7 @@ func (h ApplicationHandler) FactCreate(ctx *gin.Context) {
 // @produce json
 // @success 204
 // @router /applications/{id}/facts/{key} [put]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param key path string true "Fact key"
 // @param fact body object true "Fact value"
 func (h ApplicationHandler) FactPut(ctx *gin.Context) {
@@ -822,7 +826,7 @@ func (h ApplicationHandler) FactPut(ctx *gin.Context) {
 // @tags applications
 // @success 204
 // @router /applications/{id}/facts/{key} [delete]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param key path string true "Fact key"
 func (h ApplicationHandler) FactDelete(ctx *gin.Context) {
 	id := h.pk(ctx)
@@ -854,7 +858,7 @@ func (h ApplicationHandler) FactDelete(ctx *gin.Context) {
 // @tags applications
 // @success 204
 // @router /applications/{id}/facts/{source}: [put]
-// @param id path string true "Application ID"
+// @param id path int true "Application ID"
 // @param source path string true "Fact key"
 // @param factmap body api.FactMap true "Fact map"
 func (h ApplicationHandler) FactReplace(ctx *gin.Context, key FactKey) {
@@ -998,6 +1002,7 @@ func (h ApplicationHandler) AssessmentList(ctx *gin.Context) {
 // @produce json
 // @success 201 {object} api.Assessment
 // @router /applications/{id}/assessments [post]
+// @param id path int true "Application ID"
 // @param assessment body api.Assessment true "Assessment data"
 func (h ApplicationHandler) AssessmentCreate(ctx *gin.Context) {
 	application := &model.Application{}

diff --git a/api/archetype.go b/api/archetype.go
@@ -47,7 +47,7 @@ func (h ArchetypeHandler) AddRoutes(e *gin.Engine) {
 // @produce json
 // @success 200 {object} api.Archetype
 // @router /archetypes/{id} [get]
-// @param id path string true "Archetype ID"
+// @param id path int true "Archetype ID"
 func (h ArchetypeHandler) Get(ctx *gin.Context) {
 	m := &model.Archetype{}
 	id := h.pk(ctx)
@@ -168,7 +168,7 @@ func (h ArchetypeHandler) Create(ctx *gin.Context) {
 // @tags archetypes
 // @success 204
 // @router /archetypes/{id} [delete]
-// @param id path string true "Archetype ID"
+// @param id path int true "Archetype ID"
 func (h ArchetypeHandler) Delete(ctx *gin.Context) {
 	id := h.pk(ctx)
 	m := &model.Archetype{}
@@ -193,7 +193,7 @@ func (h ArchetypeHandler) Delete(ctx *gin.Context) {
 // @accept json
 // @success 204
 // @router /archetypes/{id} [put]
-// @param id path string true "Archetype ID"
+// @param id path int true "Archetype ID"
 // @param archetype body api.Archetype true "Archetype data"
 func (h ArchetypeHandler) Update(ctx *gin.Context) {
 	id := h.pk(ctx)
@@ -274,6 +274,7 @@ func (h ArchetypeHandler) AssessmentList(ctx *gin.Context) {
 // @success 201 {object} api.Assessment
 // @router /archetypes/{id}/assessments [post]
 // @param assessment body api.Assessment true "Assessment data"
+// @param id path int true "Archetype ID"
 func (h ArchetypeHandler) AssessmentCreate(ctx *gin.Context) {
 	archetype := &model.Archetype{}
 	id := h.pk(ctx)

diff --git a/api/assessment.go b/api/assessment.go
@@ -41,7 +41,7 @@ func (h AssessmentHandler) AddRoutes(e *gin.Engine) {
 // @produce json
 // @success 200 {object} api.Assessment
 // @router /assessments/{id} [get]
-// @param id path string true "Assessment ID"
+// @param id path int true "Assessment ID"
 func (h AssessmentHandler) Get(ctx *gin.Context) {
 	m := &model.Assessment{}
 	id := h.pk(ctx)
@@ -88,7 +88,7 @@ func (h AssessmentHandler) List(ctx *gin.Context) {
 // @tags assessments
 // @success 204
 // @router /assessments/{id} [delete]
-// @param id path string true "Assessment ID"
+// @param id path int true "Assessment ID"
 func (h AssessmentHandler) Delete(ctx *gin.Context) {
 	id := h.pk(ctx)
 	m := &model.Assessment{}
@@ -113,7 +113,7 @@ func (h AssessmentHandler) Delete(ctx *gin.Context) {
 // @accept json
 // @success 204
 // @router /assessments/{id} [put]
-// @param id path string true "Assessment ID"
+// @param id path int true "Assessment ID"
 // @param assessment body api.Assessment true "Assessment data"
 func (h AssessmentHandler) Update(ctx *gin.Context) {
 	id := h.pk(ctx)

diff --git a/api/bucket.go b/api/bucket.go
@@ -99,7 +99,7 @@ func (h BucketHandler) Create(ctx *gin.Context) {
 // @produce octet-stream
 // @success 200 {object} api.Bucket
 // @router /buckets/{id} [get]
-// @param id path string true "Bucket ID"
+// @param id path int true "Bucket ID"
 func (h BucketHandler) Get(ctx *gin.Context) {
 	m := &model.Bucket{}
 	id := h.pk(ctx)
@@ -123,7 +123,7 @@ func (h BucketHandler) Get(ctx *gin.Context) {
 // @tags buckets
 // @success 204
 // @router /buckets/{id} [delete]
-// @param id path string true "Bucket ID"
+// @param id path int true "Bucket ID"
 func (h BucketHandler) Delete(ctx *gin.Context) {
 	m := &model.Bucket{}
 	id := h.pk(ctx)
@@ -159,7 +159,8 @@ func (h BucketHandler) Delete(ctx *gin.Context) {
 // @produce octet-stream
 // @success 200
 // @router /buckets/{id}/{wildcard} [get]
-// @param id path string true "Task ID"
+// @param id path int true "Task ID"
+// @param wildcard path string true "Content path"
 // @param filter query string false "Filter"
 func (h BucketHandler) BucketGet(ctx *gin.Context) {
 	h.bucketGet(ctx, h.pk(ctx))
@@ -172,7 +173,8 @@ func (h BucketHandler) BucketGet(ctx *gin.Context) {
 // @produce json
 // @success 204
 // @router /buckets/{id}/{wildcard} [post]
-// @param id path string true "Bucket ID"
+// @param id path int true "Bucket ID"
+// @param wildcard path string true "Content path"
 func (h BucketHandler) BucketPut(ctx *gin.Context) {
 	h.bucketPut(ctx, h.pk(ctx))
 }
@@ -184,7 +186,8 @@ func (h BucketHandler) BucketPut(ctx *gin.Context) {
 // @produce json
 // @success 204
 // @router /buckets/{id}/{wildcard} [delete]
-// @param id path string true "Bucket ID"
+// @param id path int true "Bucket ID"
+// @param wildcard path string true "Content path"
 func (h BucketHandler) BucketDelete(ctx *gin.Context) {
 	h.bucketDelete(ctx, h.pk(ctx))
 }