Skip to content

Commit cb6403c

Browse files
emosbaughemosbaugh
authored
chore(api): generated docs - fixes (#2198)
1 parent 331ea0d commit cb6403c

File tree

9 files changed

+133
-156
lines changed

9 files changed

+133
-156
lines changed

‎api/Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ SHELL := /bin/bash
33
.PHONY: swagger
44
swagger:
55
swag fmt -g api.go
6-
swag init -g api.go
6+
swag init --v3.1 -g api.go
77

88
.PHONY: swag
99
swag:
10-
which swag || (go install github.com/swaggo/swag/cmd/swag@latest)
10+
which swag || (go install github.com/swaggo/swag/v2/cmd/swag@latest)

‎api/api.go‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import (
1010
"github.com/replicatedhq/embedded-cluster/api/controllers/auth"
1111
"github.com/replicatedhq/embedded-cluster/api/controllers/console"
1212
"github.com/replicatedhq/embedded-cluster/api/controllers/install"
13-
_ "github.com/replicatedhq/embedded-cluster/api/docs"
13+
"github.com/replicatedhq/embedded-cluster/api/docs"
1414
"github.com/replicatedhq/embedded-cluster/api/types"
1515
"github.com/sirupsen/logrus"
1616
httpSwagger "github.com/swaggo/http-swagger/v2"
@@ -28,10 +28,9 @@ import (
2828
// @license.name Apache 2.0
2929
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
3030

31-
// @host localhost:30080
3231
// @BasePath /api
3332

34-
// @securityDefinitions.basic BasicAuth
33+
// @securityDefinitions.bearerauth bearerauth
3534

3635
// @externalDocs.description OpenAPI
3736
// @externalDocs.url https://swagger.io/resources/open-api/
@@ -114,6 +113,14 @@ func New(password string, opts ...APIOption) (*API, error) {
114113

115114
func (a *API) RegisterRoutes(router *mux.Router) {
116115
router.HandleFunc("/health", a.getHealth).Methods("GET")
116+
117+
// Hack to fix issue
118+
// https://github.com/swaggo/swag/issues/1588#issuecomment-2797801240
119+
router.HandleFunc("/swagger/doc.json", func(w http.ResponseWriter, _ *http.Request) {
120+
w.Header().Set("Content-Type", "application/json")
121+
w.WriteHeader(200)
122+
w.Write([]byte(docs.SwaggerInfo.ReadDoc()))
123+
}).Methods("GET")
117124
router.PathPrefix("/swagger/").Handler(httpSwagger.WrapHandler)
118125

119126
router.HandleFunc("/auth/login", a.postAuthLogin).Methods("POST")

‎api/docs/docs.go‎

Lines changed: 11 additions & 67 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎api/docs/swagger.json‎

Lines changed: 8 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,10 @@
11
{
2-
"swagger": "2.0",
3-
"info": {
4-
"description": "This is the API for the Embedded Cluster project.",
5-
"title": "Embedded Cluster API",
6-
"termsOfService": "http://swagger.io/terms/",
7-
"contact": {
8-
"name": "API Support",
9-
"url": "https://github.com/replicatedhq/embedded-cluster/issues",
10-
"email": "[email protected]"
11-
},
12-
"license": {
13-
"name": "Apache 2.0",
14-
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
15-
},
16-
"version": "0.1"
17-
},
18-
"host": "localhost:30080",
19-
"basePath": "/api",
20-
"paths": {
21-
"/health": {
22-
"get": {
23-
"description": "get the health of the API",
24-
"consumes": [
25-
"application/json"
26-
],
27-
"produces": [
28-
"application/json"
29-
],
30-
"tags": [
31-
"health"
32-
],
33-
"summary": "Get the health of the API",
34-
"responses": {
35-
"200": {
36-
"description": "OK",
37-
"schema": {
38-
"$ref": "#/definitions/types.Health"
39-
}
40-
}
41-
}
42-
}
43-
}
44-
},
45-
"definitions": {
46-
"types.Health": {
47-
"type": "object",
48-
"properties": {
49-
"status": {
50-
"type": "string"
51-
}
52-
}
53-
}
54-
},
55-
"securityDefinitions": {
56-
"BasicAuth": {
57-
"type": "basic"
58-
}
59-
},
60-
"externalDocs": {
61-
"description": "OpenAPI",
62-
"url": "https://swagger.io/resources/open-api/"
63-
}
2+
"components": {"schemas":{"types.Health":{"properties":{"status":{"type":"string"}},"type":"object"},"types.Install":{"properties":{"config":{"$ref":"#/components/schemas/types.InstallationConfig"},"status":{"$ref":"#/components/schemas/types.InstallationStatus"}},"type":"object"},"types.InstallationConfig":{"properties":{"adminConsolePort":{"type":"integer"},"dataDirectory":{"type":"string"},"globalCidr":{"type":"string"},"httpProxy":{"type":"string"},"httpsProxy":{"type":"string"},"localArtifactMirrorPort":{"type":"integer"},"networkInterface":{"type":"string"},"noProxy":{"type":"string"},"podCidr":{"type":"string"},"serviceCidr":{"type":"string"}},"type":"object"},"types.InstallationState":{"type":"string","x-enum-varnames":["InstallationStatePending","InstallationStateRunning","InstallationStateSucceeded","InstallationStateFailed"]},"types.InstallationStatus":{"properties":{"description":{"type":"string"},"lastUpdated":{"type":"string"},"state":{"$ref":"#/components/schemas/types.InstallationState"}},"type":"object"}},"securitySchemes":{"bearerauth":{"bearerFormat":"JWT","scheme":"bearer","type":"http"}}},
3+
"info": {"contact":{"email":"[email protected]","name":"API Support","url":"https://github.com/replicatedhq/embedded-cluster/issues"},"description":"This is the API for the Embedded Cluster project.","license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"},"termsOfService":"http://swagger.io/terms/","title":"Embedded Cluster API","version":"0.1"},
4+
"externalDocs": {"description":"OpenAPI","url":"https://swagger.io/resources/open-api/"},
5+
"paths": {"/health":{"get":{"description":"get the health of the API","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.Health"}}},"description":"OK"}},"summary":"Get the health of the API","tags":["health"]}},"/install":{"get":{"description":"get the install object","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/types.Install"}}},"description":"OK"}},"security":[{"bearerauth":[]}],"summary":"Get the install object","tags":["install"]}}},
6+
"openapi": "3.1.0",
7+
"servers": [
8+
{"url":"/api"}
9+
]
6410
}

‎api/docs/swagger.yaml‎

Lines changed: 80 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,64 @@
1-
basePath: /api
2-
definitions:
3-
types.Health:
4-
properties:
5-
status:
6-
type: string
7-
type: object
1+
components:
2+
schemas:
3+
types.Health:
4+
properties:
5+
status:
6+
type: string
7+
type: object
8+
types.Install:
9+
properties:
10+
config:
11+
$ref: '#/components/schemas/types.InstallationConfig'
12+
status:
13+
$ref: '#/components/schemas/types.InstallationStatus'
14+
type: object
15+
types.InstallationConfig:
16+
properties:
17+
adminConsolePort:
18+
type: integer
19+
dataDirectory:
20+
type: string
21+
globalCidr:
22+
type: string
23+
httpProxy:
24+
type: string
25+
httpsProxy:
26+
type: string
27+
localArtifactMirrorPort:
28+
type: integer
29+
networkInterface:
30+
type: string
31+
noProxy:
32+
type: string
33+
podCidr:
34+
type: string
35+
serviceCidr:
36+
type: string
37+
type: object
38+
types.InstallationState:
39+
type: string
40+
x-enum-varnames:
41+
- InstallationStatePending
42+
- InstallationStateRunning
43+
- InstallationStateSucceeded
44+
- InstallationStateFailed
45+
types.InstallationStatus:
46+
properties:
47+
description:
48+
type: string
49+
lastUpdated:
50+
type: string
51+
state:
52+
$ref: '#/components/schemas/types.InstallationState'
53+
type: object
54+
securitySchemes:
55+
bearerauth:
56+
bearerFormat: JWT
57+
scheme: bearer
58+
type: http
859
externalDocs:
960
description: OpenAPI
1061
url: https://swagger.io/resources/open-api/
11-
host: localhost:30080
1262
info:
1363
contact:
1464
email: [email protected]
@@ -21,23 +71,35 @@ info:
2171
termsOfService: http://swagger.io/terms/
2272
title: Embedded Cluster API
2373
version: "0.1"
74+
openapi: 3.1.0
2475
paths:
2576
/health:
2677
get:
27-
consumes:
28-
- application/json
2978
description: get the health of the API
30-
produces:
31-
- application/json
3279
responses:
3380
"200":
81+
content:
82+
application/json:
83+
schema:
84+
$ref: '#/components/schemas/types.Health'
3485
description: OK
35-
schema:
36-
$ref: '#/definitions/types.Health'
3786
summary: Get the health of the API
3887
tags:
3988
- health
40-
securityDefinitions:
41-
BasicAuth:
42-
type: basic
43-
swagger: "2.0"
89+
/install:
90+
get:
91+
description: get the install object
92+
responses:
93+
"200":
94+
content:
95+
application/json:
96+
schema:
97+
$ref: '#/components/schemas/types.Install'
98+
description: OK
99+
security:
100+
- bearerauth: []
101+
summary: Get the install object
102+
tags:
103+
- install
104+
servers:
105+
- url: /api

‎api/health.go‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ import (
1111
// @Summary Get the health of the API
1212
// @Description get the health of the API
1313
// @Tags health
14-
// @Accept json
1514
// @Produce json
1615
// @Success 200 {object} types.Health
1716
// @Router /health [get]

‎api/install.go‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ import (
77
"github.com/replicatedhq/embedded-cluster/api/types"
88
)
99

10+
// getInstall handler to get the install object
11+
//
12+
// @Summary Get the install object
13+
// @Description get the install object
14+
// @Tags install
15+
// @Security bearerauth
16+
// @Produce json
17+
// @Success 200 {object} types.Install
18+
// @Router /install [get]
1019
func (a *API) getInstall(w http.ResponseWriter, r *http.Request) {
1120
install, err := a.installController.Get(r.Context())
1221
if err != nil {

‎go.mod‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ require (
3939
github.com/spf13/viper v1.20.1
4040
github.com/stretchr/testify v1.10.0
4141
github.com/swaggo/http-swagger/v2 v2.0.2
42-
github.com/swaggo/swag v1.16.4
42+
github.com/swaggo/swag/v2 v2.0.0-rc4
4343
github.com/urfave/cli/v2 v2.27.6
4444
github.com/vmware-tanzu/velero v1.16.0
4545
go.uber.org/multierr v1.11.0
@@ -263,7 +263,9 @@ require (
263263
github.com/stefanberger/go-pkcs11uri v0.0.0-20230803200340-78284954bff6 // indirect
264264
github.com/stretchr/objx v0.5.2 // indirect
265265
github.com/subosito/gotenv v1.6.0 // indirect
266+
github.com/sv-tools/openapi v0.2.1 // indirect
266267
github.com/swaggo/files/v2 v2.0.2 // indirect
268+
github.com/swaggo/swag v1.8.1 // indirect
267269
github.com/sylabs/sif/v2 v2.20.2 // indirect
268270
github.com/tchap/go-patricia/v2 v2.3.2 // indirect
269271
github.com/titanous/rocacheck v0.0.0-20171023193734-afe73141d399 // indirect

0 commit comments

Comments
 (0)