Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(server/v2): Add Swagger UI support for server/v2 #23092

Closed
wants to merge 32 commits into from
Closed
Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
4ed5650
Create handler.go
crStiv Dec 25, 2024
2ac2555
feat(server): add swagger UI configuration
crStiv Dec 25, 2024
8930230
feat(server): integrate swagger UI setup
crStiv Dec 25, 2024
c812722
Create server.go
crStiv Dec 26, 2024
d0c20bc
Update config.go
crStiv Dec 26, 2024
ac5982a
Update config.go
crStiv Dec 26, 2024
f96dafe
Update handler.go
crStiv Dec 26, 2024
9859c38
Update server.go
crStiv Dec 26, 2024
e96e5bb
return original code
crStiv Dec 26, 2024
e733362
Update handler.go
crStiv Jan 6, 2025
34eab36
Update server.go
crStiv Jan 6, 2025
eec89d7
Update config.go
crStiv Jan 6, 2025
654cc99
Update app.go
crStiv Jan 6, 2025
c9d6544
Create doc.go
crStiv Jan 6, 2025
16556c1
Update commands.go
crStiv Jan 6, 2025
2021911
Update app.go
crStiv Jan 6, 2025
93dc4b6
Update handler.go
crStiv Jan 6, 2025
446c0f8
Update handler.go
crStiv Jan 7, 2025
c038d6c
Update doc.go
crStiv Jan 7, 2025
0938d61
Update config.go
crStiv Jan 7, 2025
2466ab5
Update handler.go
crStiv Jan 7, 2025
8a042b2
Update commands.go
crStiv Jan 7, 2025
8ccb884
Update doc.go
crStiv Jan 7, 2025
9659ba7
Update server.go
crStiv Jan 7, 2025
8f3017c
Merge branch 'main' into feat/add-swagger-ui
crStiv Jan 7, 2025
0fa0b6b
Update server.go
crStiv Jan 8, 2025
35f2fad
Update handler.go
crStiv Jan 8, 2025
44da58f
Update server.go
crStiv Jan 8, 2025
98f2d85
Update server.go
crStiv Jan 11, 2025
a3dbbe8
Merge branch 'main' into feat/add-swagger-ui
crStiv Jan 11, 2025
d88e065
Update server.go
crStiv Jan 19, 2025
54fe590
Update doc.go
crStiv Jan 19, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions server/v2/api/swagger/config.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
package swagger

import "github.com/cosmos/cosmos-sdk/server/v2/config"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Package import oversight
Currently, you're importing "github.com/cosmos/cosmos-sdk/server/v2/config" but using fmt.Errorf in the code without importing "fmt". There's no direct usage of the imported "github.com/cosmos/cosmos-sdk/server/v2/config" in this snippet. If it's needed in other parts of the file, that's fine. Otherwise, consider adding the missing "fmt" import or removing unused imports.

 package swagger

-import "github.com/cosmos/cosmos-sdk/server/v2/config"
+import (
+    "fmt"
+    "github.com/cosmos/cosmos-sdk/server/v2/config"
+)
 

Committable suggestion skipped: line range outside the PR's diff.

// Config represents Swagger configuration options
type Config struct {
// Enable enables the Swagger UI endpoint
Enable bool `mapstructure:"enable"`
// Path is the URL path where Swagger UI will be served
Path string `mapstructure:"path"`
}

// DefaultConfig returns default configuration for Swagger
func DefaultConfig() Config {
return Config{
Enable: false,
Path: "/swagger",
}
}

// Validate validates the configuration
func (c Config) Validate() error {
if c.Path == "" {
return fmt.Errorf("swagger path cannot be empty")
}
return nil
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Ensure error formatting is enabled
While the validation logic is correct, remember that fmt.Errorf("swagger path cannot be empty") requires "fmt" to be imported (as noted above). Once the import is added, this code works as intended.

🧰 Tools
🪛 golangci-lint (1.62.2)

24-24: undefined: fmt

(typecheck)

46 changes: 46 additions & 0 deletions server/v2/api/swagger/handler.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
package swagger

import (
"net/http"
"path"
"path/filepath"
"strings"

"github.com/rakyll/statik/fs"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Add Required Dependency for Statik

The pipeline indicates that the module github.com/rakyll/statik/fs is missing from project dependencies. Update your go.mod by explicitly adding this dependency to avoid build failures.

Would you like assistance creating a diff to add github.com/rakyll/statik to your go.mod file?

🧰 Tools
🪛 GitHub Actions: Dependency Review

[error] 10-10: Missing required module: github.com/rakyll/statik/fs. Module needs to be added to the project dependencies.

)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Missing time import
You're calling time.Time{} in this file but haven't imported "time". Add the missing import to avoid compilation issues.

 import (
     "net/http"
     "path"
     "path/filepath"
     "strings"

     "github.com/rakyll/statik/fs"
+    "time"
 )

Committable suggestion skipped: line range outside the PR's diff.


// Handler returns an HTTP handler that serves the Swagger UI files
func Handler(statikFS http.FileSystem) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
// If the path is empty or "/", show index.html
if r.URL.Path == "/" || r.URL.Path == "" {
r.URL.Path = "/index.html"
}

// Clearing the path
urlPath := path.Clean(r.URL.Path)

// Opening the file from statikFS
f, err := statikFS.Open(urlPath)
if err != nil {
w.WriteHeader(http.StatusNotFound)
return
}
defer f.Close()

// Determining the content-type
ext := strings.ToLower(filepath.Ext(urlPath))
switch ext {
case ".html":
w.Header().Set("Content-Type", "text/html")
case ".css":
w.Header().Set("Content-Type", "text/css")
case ".js":
w.Header().Set("Content-Type", "application/javascript")
case ".json":
w.Header().Set("Content-Type", "application/json")
}

http.ServeContent(w, r, urlPath, time.Time{}, f)
}
}
19 changes: 19 additions & 0 deletions server/v2/server.go
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, thanks for tackling this. The wiring shouldn't be done in the main server, but api/swagger should be its own server component. Check out the other servers.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, thanks for tackling this. The wiring shouldn't be done in the main server, but api/swagger should be its own server component. Check out the other servers.

oh you're absolutely right, gonna fix it soon!

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@julienrbrt sorry for mess in commits, I had to redo some things but now everything should be fine

Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,14 @@ import (
"path/filepath"
"strings"

"github.com/cosmos/cosmos-sdk/server/v2/api/swagger"
"github.com/pelletier/go-toml/v2"
"github.com/spf13/cobra"
"github.com/spf13/pflag"

"cosmossdk.io/core/transaction"
"cosmossdk.io/log"
"github.com/rakyll/statik/fs"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Check for missing imports
You reference swagger and statik/fs but also rely on http.ServeMux later (lines 78, 88) without importing "net/http". Ensure all required imports are present to avoid compilation errors.

 import (
     "context"
     "errors"
     "fmt"
     "os"
     "path/filepath"
     "strings"

+    "net/http"
     "github.com/cosmos/cosmos-sdk/server/v2/api/swagger"
     "github.com/pelletier/go-toml/v2"
     "github.com/spf13/cobra"

Committable suggestion skipped: line range outside the PR's diff.

)

// ServerComponent is a server component that can be started and stopped.
Expand Down Expand Up @@ -73,6 +75,7 @@ var _ ServerComponent[transaction.Tx] = (*Server[transaction.Tx])(nil)
type Server[T transaction.Tx] struct {
components []ServerComponent[T]
config ServerConfig
router *http.ServeMux
}

func NewServer[T transaction.Tx](
Expand All @@ -82,6 +85,7 @@ func NewServer[T transaction.Tx](
return &Server[T]{
config: config,
components: components,
router: http.NewServeMux(),
}
}

Expand Down Expand Up @@ -242,3 +246,18 @@ func (s *Server[T]) StartFlags() []*pflag.FlagSet {

return flags
}

func (s *Server[T]) setupSwagger() error {
cfg := s.config.API.Swagger
if !cfg.Enable {
return nil
}

statikFS, err := fs.New()
if err != nil {
return err
}

s.router.PathPrefix(cfg.Path).Handler(swagger.Handler(statikFS))
return nil
}
Loading