Add openAPI #47

atsushii · 2022-06-18T14:58:57Z

Addresses #9

What I did

Create openAPI doc for current REST APIs
Add docker to run swagger-u by go-swagger
Generate spec YAML by swaggo (https://github.com/swaggo/swag)

Please check the doc!

step

1, mage run
2, access to http://localhost:8002/docs

aqaurius6666 · 2022-06-22T08:45:34Z

how did you generate openapi.yaml file?

atsushii · 2022-06-22T10:57:40Z

@aqaurius6666
~~Using https://test-sso.stoplight.io/~~

https://github.com/swaggo/swag

decentralgabe · 2022-06-22T17:18:31Z

Thank you for the PR, @atsushii

I am weighing the tradeoff of managing this API file separately, as opposed to using annotations like https://github.com/swaggo/swag

Annotations have the benefit of being next to the API code, which I think will have the effect of keeping the docs more up to date, and also simpler to read - since you can see the API exposed by looking at the code.

I looked at stoplight but the documentation is a bit sparse. It's most important that we're able to keep these docs up to date and easy to read. What do you think?

atsushii · 2022-06-22T23:30:49Z

@decentralgabe
I agree with your idea that keep these docs up to date and easy to read!
I will definitely fix my PR. Thanks for the advice!

atsushii · 2022-06-25T05:53:31Z

@decentralgabe

I have fixed my code to generate spec yaml by annotations using https://github.com/swaggo/swag

Please review it!

decentralgabe · 2022-06-25T18:47:11Z

thank you @atsushii this looks really good. I will take a more in depth look after the weekend.

decentralgabe

minor changes - looks good!

decentralgabe · 2022-06-28T23:00:13Z

cmd/main.go

+// @title           Swagger Example API
+// @version         1.0
+// @description     This is a sample server celler server.
+// @termsOfService  http://swagger.io/terms/
+
+// @contact.name   API Support
+// @contact.url    http://www.swagger.io/support
+// @contact.email  [email protected]
+
+// @license.name  Apache 2.0
+// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html
+
+// @host      localhost:8080


Suggested change

// @title Swagger Example API

// @version 1.0

// @description This is a sample server celler server.

// @termsOfService http://swagger.io/terms/

// @contact.name API Support

// @contact.url http://www.swagger.io/support

// @contact.email [email protected]

// @license.name Apache 2.0

// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080

// @title SSI Service API

// @version 0.1

// @description https://github.com/TBD54566975/ssi-service

// @contact.name TBD

// @contact.url https://github.com/TBD54566975/ssi-service/issues

// @contact.email [email protected]

// @license.name Apache 2.0

// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:8080

decentralgabe · 2022-06-28T23:00:48Z

pkg/server/router/credential.go

@@ -62,6 +63,17 @@ type CreateCredentialResponse struct {
 	Credential credsdk.VerifiableCredential `json:"credential"`
 }

+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// CreateCredential godoc

decentralgabe · 2022-06-28T23:00:58Z

pkg/server/router/credential.go

@@ -87,6 +99,16 @@ type GetCredentialResponse struct {
 	Credential credsdk.VerifiableCredential `json:"credential"`
 }

+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// GetCredential godoc

decentralgabe · 2022-06-28T23:01:11Z

pkg/server/router/credential.go

@@ -113,7 +135,19 @@ type GetCredentialsResponse struct {
 	Credentials []credsdk.VerifiableCredential `json:"credentials"`
 }

-// GetCredentials checks for the presence of a query parameter and calls the associated filtered get method
+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// GetCredentials godoc

decentralgabe · 2022-06-28T23:01:21Z

pkg/server/router/credential.go

@@ -174,6 +208,17 @@ func (cr CredentialRouter) getCredentialsBySchema(schema string, ctx context.Con
 	return framework.Respond(ctx, w, resp, http.StatusOK)
 }

+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// DeleteCredential godoc

decentralgabe · 2022-06-28T23:02:55Z

pkg/server/router/health.go

@@ -14,7 +15,14 @@ const (
 	HealthOK string = "OK"
 )

-// Health is a simple handler that always responds with a 200 OK
+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// Health godoc

decentralgabe · 2022-06-28T23:03:08Z

pkg/server/router/health.go

+// ShowAccount godoc
+// @Summary          Health Check
+// @Description      Health is a simple handler that always responds with a 200 OK
+// @Tags             NewSSIServer


what purpose does the tag server here?

I fix it to HealthCheck, thanks!

decentralgabe · 2022-06-28T23:03:20Z

pkg/server/router/readiness.go

@@ -23,8 +24,15 @@ type GetReadinessResponse struct {
 	ServiceStatuses map[svcframework.Type]svcframework.Status `json:"serviceStatuses"`
 }

-// ready runs a number of application specific checks to see if all the
-// relied upon service are healthy. Should return a 500 if not ready.
+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// Readiness godoc

decentralgabe · 2022-06-28T23:03:33Z

pkg/server/router/schema.go

@@ -40,6 +41,17 @@ type CreateSchemaResponse struct {
 	Schema schemalib.VCJSONSchema `json:"schema"`
 }

+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// CreateSchema godoc

decentralgabe · 2022-06-28T23:03:44Z

pkg/server/router/schema.go

@@ -79,6 +100,16 @@ type GetSchemaResponse struct {
 	Schema schemalib.VCJSONSchema `json:"schema,omitempty"`
 }

+// ShowAccount godoc


Suggested change

// ShowAccount godoc

// GetSchemaByID godoc

decentralgabe · 2022-06-28T23:20:39Z

docs/.swaggo

@@ -0,0 +1,2 @@
+// TODO: read cryptosuite.LDKeyType from sdk properly
+skip github.com/TBD54566975/ssi-sdk/did.VerificationMethod


this should be solved before merge, what error did you run into?

@decentralgabe
ParseComment error in file {path to did.go} :cannot find type definition: cryptosuite.LDKeyType
the above error occurred when I ran swag init cmd.

Seems cannot read LDKeyType which define inside ssi-sdk

probably need to fix the type definition in ssi-sdk..
What do you think?

@decentralgabe

let me take a look. do you mind if I push to the branch if I find a solution?

decentralgabe · 2022-07-05T23:56:03Z

hi @atsushii I created a PR against your branch here that fixes the issues. if you merge this into your branch, I believe this PR should update automatically: atsushii#1

… into feature/add-swagger

atsushii · 2022-07-06T14:04:11Z

Hi @decentralgabe
Thank you for your help! Already Marged your PR and fixed all of your review comments.
Please review my PR!

decentralgabe

awesome job, thank you for your contribution!

add: openAPI doc

ebd69ef

atsushii requested review from decentralgabe and mistermoe as code owners June 18, 2022 14:58

atsushii added 6 commits June 23, 2022 09:15

Merge branch 'main' into feature/add-swagger

c9d9a30

fix: magefile

cde9e30

add: annotation

d318a22

add: annotation

7abfdba

rm

5545586

generate spec yaml by swaggo

30a87c0

run mod tidy

c8ef4e0

decentralgabe suggested changes Jun 28, 2022

View reviewed changes

decentralgabe reviewed Jun 28, 2022

View reviewed changes

fix: review

2ffe7b0

atsushii requested a review from decentralgabe July 2, 2022 09:51

update to latest ssi sdk; install swag if not present

d60d3c2

Gabe and others added 4 commits July 5, 2022 16:56

Merge branch 'main' into feature/add-swagger

fb46f18

Merge branch 'main' into feature/add-swagger

fa85e0f

Merge branch 'feature/add-swagger' of github.com:atsushii/ssi-service…

f708c41

… into feature/add-swagger

fix: comflict

9393ad4

decentralgabe approved these changes Jul 6, 2022

View reviewed changes

decentralgabe merged commit bf83a59 into TBD54566975:main Jul 6, 2022

decentralgabe mentioned this pull request Jul 6, 2022

OpenAPI / Swagger spec for REST API #9

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add openAPI #47

Add openAPI #47

atsushii commented Jun 18, 2022 •

edited

Loading

aqaurius6666 commented Jun 22, 2022

atsushii commented Jun 22, 2022 •

edited

Loading

decentralgabe commented Jun 22, 2022

atsushii commented Jun 22, 2022

atsushii commented Jun 25, 2022

decentralgabe commented Jun 25, 2022

decentralgabe left a comment

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

atsushii Jul 2, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

decentralgabe Jun 28, 2022

atsushii Jul 2, 2022 •

edited

Loading

atsushii Jul 2, 2022

decentralgabe Jul 5, 2022

decentralgabe commented Jul 5, 2022 •

edited

Loading

atsushii commented Jul 6, 2022

decentralgabe left a comment

		@@ -0,0 +1,2 @@
		// TODO: read cryptosuite.LDKeyType from sdk properly
		skip github.com/TBD54566975/ssi-sdk/did.VerificationMethod

Add openAPI #47

Add openAPI #47

Conversation

atsushii commented Jun 18, 2022 • edited Loading

aqaurius6666 commented Jun 22, 2022

atsushii commented Jun 22, 2022 • edited Loading

decentralgabe commented Jun 22, 2022

atsushii commented Jun 22, 2022

atsushii commented Jun 25, 2022

decentralgabe commented Jun 25, 2022

decentralgabe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsushii Jul 2, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

decentralgabe commented Jul 5, 2022 • edited Loading

atsushii commented Jul 6, 2022

decentralgabe left a comment

Choose a reason for hiding this comment

atsushii commented Jun 18, 2022 •

edited

Loading

atsushii commented Jun 22, 2022 •

edited

Loading

atsushii Jul 2, 2022 •

edited

Loading

decentralgabe commented Jul 5, 2022 •

edited

Loading