From b6ff832e50bd4f197d565fbca6f4e0bef8cd237c Mon Sep 17 00:00:00 2001 From: Maksim Merzhanov Date: Wed, 8 Apr 2026 16:07:10 +0300 Subject: [PATCH] api: update swagger --- api/debug.go | 24 ++-- api/peers.go | 126 +++++++++---------- api/settings.go | 64 +++++----- application.go | 12 +- docs/swagger.yaml | 309 ++++++++++++++++++++++++++++++++++------------ p2p/metrics.go | 4 +- 6 files changed, 345 insertions(+), 194 deletions(-) diff --git a/api/debug.go b/api/debug.go index 2e7ab880..5bbac757 100644 --- a/api/debug.go +++ b/api/debug.go @@ -16,11 +16,11 @@ import ( "github.com/anywherelan/awl/entity" ) -// @Tags Debug -// @Summary Get p2p debug info -// @Produce json -// @Success 200 {object} entity.P2pDebugInfo -// @Router /debug/p2p_info [GET] +// @Tags Debug +// @Summary Get p2p debug info +// @Produce json +// @Success 200 {object} entity.P2pDebugInfo +// @Router /debug/p2p_info [GET] func (h *Handler) GetP2pDebugInfo(c echo.Context) (err error) { metricsByProtocol := h.p2p.NetworkStatsByProtocol() bandwidthByProtocol := make(map[string]entity.BandwidthInfo, len(metricsByProtocol)) @@ -62,13 +62,13 @@ func (h *Handler) GetP2pDebugInfo(c echo.Context) (err error) { return c.JSONPretty(http.StatusOK, debugInfo, " ") } -// @Tags Debug -// @Summary Get logs -// @Param logs query int false "Define number of rows of logs to output. On default and 0 prints all." -// @Param from_head query bool false "Print logs from the beginning of logs" -// @Produce plain -// @Success 200 {string} string "log text" -// @Router /debug/log [GET] +// @Tags Debug +// @Summary Get logs +// @Param logs query int false "Define number of rows of logs to output. On default and 0 prints all." +// @Param from_head query bool false "Print logs from the beginning of logs" +// @Produce plain +// @Success 200 {string} string "log text" +// @Router /debug/log [GET] func (h *Handler) GetLog(c echo.Context) (err error) { req := entity.LogRequest{} err = c.Bind(&req) diff --git a/api/peers.go b/api/peers.go index 3692f413..da47b694 100644 --- a/api/peers.go +++ b/api/peers.go @@ -15,12 +15,12 @@ import ( const ErrorPeerAliasIsNotUniq = "peer name is not unique" -// @Tags Peers -// @Summary Get known peers info -// @Accept json -// @Produce json -// @Success 200 {array} entity.KnownPeersResponse -// @Router /peers/get_known [GET] +// @Tags Peers +// @Summary Get known peers info +// @Accept json +// @Produce json +// @Success 200 {array} entity.KnownPeersResponse +// @Router /peers/get_known [GET] func (h *Handler) GetKnownPeers(c echo.Context) (err error) { result := h.getKnownPeers() return c.JSON(http.StatusOK, result) @@ -71,15 +71,15 @@ func (h *Handler) getKnownPeers() []entity.KnownPeersResponse { return result } -// @Tags Peers -// @Summary Get known peer settings -// @Accept json -// @Produce json -// @Param body body entity.PeerIDRequest true "Params" -// @Success 200 {object} config.KnownPeer -// @Failure 400 {object} api.Error -// @Failure 404 {object} api.Error -// @Router /peers/get_known_peer_settings [POST] +// @Tags Peers +// @Summary Get known peer settings +// @Accept json +// @Produce json +// @Param body body entity.PeerIDRequest true "Params" +// @Success 200 {object} config.KnownPeer +// @Failure 400 {object} api.Error +// @Failure 404 {object} api.Error +// @Router /peers/get_known_peer_settings [POST] func (h *Handler) GetKnownPeerSettings(c echo.Context) (err error) { req := entity.PeerIDRequest{} err = c.Bind(&req) @@ -97,15 +97,15 @@ func (h *Handler) GetKnownPeerSettings(c echo.Context) (err error) { return c.JSON(http.StatusOK, knownPeer) } -// @Tags Peers -// @Summary Update peer settings -// @Accept json -// @Produce json -// @Param body body entity.UpdatePeerSettingsRequest true "Params" -// @Success 200 "OK" -// @Failure 400 {object} api.Error -// @Failure 404 {object} api.Error -// @Router /peers/update_settings [POST] +// @Tags Peers +// @Summary Update peer settings +// @Accept json +// @Produce json +// @Param body body entity.UpdatePeerSettingsRequest true "Params" +// @Success 200 "OK" +// @Failure 400 {object} api.Error +// @Failure 404 {object} api.Error +// @Router /peers/update_settings [POST] func (h *Handler) UpdatePeerSettings(c echo.Context) (err error) { req := entity.UpdatePeerSettingsRequest{} err = c.Bind(&req) @@ -151,15 +151,15 @@ func (h *Handler) UpdatePeerSettings(c echo.Context) (err error) { return c.NoContent(http.StatusOK) } -// @Tags Peers -// @Summary Invite new peer -// @Accept json -// @Produce json -// @Param body body entity.FriendRequest true "Params" -// @Success 200 "OK" -// @Failure 400 {object} api.Error -// @Failure 500 {object} api.Error -// @Router /peers/invite_peer [POST] +// @Tags Peers +// @Summary Invite new peer +// @Accept json +// @Produce json +// @Param body body entity.FriendRequest true "Params" +// @Success 200 "OK" +// @Failure 400 {object} api.Error +// @Failure 500 {object} api.Error +// @Router /peers/invite_peer [POST] func (h *Handler) SendFriendRequest(c echo.Context) (err error) { req := entity.FriendRequest{} err = c.Bind(&req) @@ -188,15 +188,15 @@ func (h *Handler) SendFriendRequest(c echo.Context) (err error) { return c.NoContent(http.StatusOK) } -// @Tags Peers -// @Summary Accept new peer's invitation -// @Accept json -// @Produce json -// @Param body body entity.FriendRequestReply true "Params" -// @Success 200 "OK" -// @Failure 400 {object} api.Error -// @Failure 500 {object} api.Error -// @Router /peers/accept_peer [POST] +// @Tags Peers +// @Summary Accept new peer's invitation +// @Accept json +// @Produce json +// @Param body body entity.FriendRequestReply true "Params" +// @Success 200 "OK" +// @Failure 400 {object} api.Error +// @Failure 500 {object} api.Error +// @Router /peers/accept_peer [POST] func (h *Handler) AcceptFriend(c echo.Context) (err error) { req := entity.FriendRequestReply{} err = c.Bind(&req) @@ -236,12 +236,12 @@ func (h *Handler) AcceptFriend(c echo.Context) (err error) { return c.NoContent(http.StatusOK) } -// @Tags Peers -// @Summary Get ingoing auth requests -// @Accept json -// @Produce json -// @Success 200 {array} entity.AuthRequest -// @Router /peers/auth_requests [GET] +// @Tags Peers +// @Summary Get ingoing auth requests +// @Accept json +// @Produce json +// @Success 200 {array} entity.AuthRequest +// @Router /peers/auth_requests [GET] func (h *Handler) GetAuthRequests(c echo.Context) (err error) { authRequestsMap := h.authStatus.GetIngoingAuthRequests() authRequests := make([]entity.AuthRequest, 0, len(authRequestsMap)) @@ -271,15 +271,15 @@ func (h *Handler) GetAuthRequests(c echo.Context) (err error) { return c.JSON(http.StatusOK, authRequests) } -// @Tags Peers -// @Summary Remove known peer -// @Accept json -// @Produce json -// @Param body body entity.PeerIDRequest true "Params" -// @Success 200 "OK" -// @Failure 400 {object} api.Error -// @Failure 404 {object} api.Error -// @Router /peers/remove [POST] +// @Tags Peers +// @Summary Remove known peer +// @Accept json +// @Produce json +// @Param body body entity.PeerIDRequest true "Params" +// @Success 200 "OK" +// @Failure 400 {object} api.Error +// @Failure 404 {object} api.Error +// @Router /peers/remove [POST] func (h *Handler) RemovePeer(c echo.Context) (err error) { req := entity.PeerIDRequest{} err = c.Bind(&req) @@ -306,12 +306,12 @@ func (h *Handler) RemovePeer(c echo.Context) (err error) { return c.NoContent(http.StatusOK) } -// @Tags Peers -// @Summary Get blocked peers info -// @Accept json -// @Produce json -// @Success 200 {array} config.BlockedPeer -// @Router /peers/get_blocked [GET] +// @Tags Peers +// @Summary Get blocked peers info +// @Accept json +// @Produce json +// @Success 200 {array} config.BlockedPeer +// @Router /peers/get_blocked [GET] func (h *Handler) GetBlockedPeers(c echo.Context) (err error) { h.conf.RLock() result := make([]config.BlockedPeer, 0, len(h.conf.BlockedPeers)) diff --git a/api/settings.go b/api/settings.go index 784bc8a0..a9941bed 100644 --- a/api/settings.go +++ b/api/settings.go @@ -9,12 +9,12 @@ import ( "github.com/anywherelan/awl/entity" ) -// @Tags Settings -// @Summary Get my peer info -// @Accept json -// @Produce json -// @Success 200 {object} entity.PeerInfo -// @Router /settings/peer_info [GET] +// @Tags Settings +// @Summary Get my peer info +// @Accept json +// @Produce json +// @Success 200 {object} entity.PeerInfo +// @Router /settings/peer_info [GET] func (h *Handler) GetMyPeerInfo(c echo.Context) (err error) { totalBootstraps, connectedBootstraps := h.p2p.BootstrapPeersStats() netStats := h.p2p.NetworkStats() @@ -51,13 +51,13 @@ func (h *Handler) GetMyPeerInfo(c echo.Context) (err error) { return c.JSON(http.StatusOK, peerInfo) } -// @Tags Settings -// @Summary Update my peer info -// @Accept json -// @Produce json -// @Param body body entity.UpdateMySettingsRequest true "Params" -// @Success 200 "OK" -// @Router /settings/update [POST] +// @Tags Settings +// @Summary Update my peer info +// @Accept json +// @Produce json +// @Param body body entity.UpdateMySettingsRequest true "Params" +// @Success 200 "OK" +// @Router /settings/update [POST] func (h *Handler) UpdateMySettings(c echo.Context) (err error) { req := entity.UpdateMySettingsRequest{} err = c.Bind(&req) @@ -80,24 +80,24 @@ func (h *Handler) UpdateMySettings(c echo.Context) (err error) { return c.NoContent(http.StatusOK) } -// @Tags Settings -// @Summary Export server configuration -// @Accept json -// @Produce json -// @Success 200 {object} config.Config -// @Router /settings/export_server_config [GET] +// @Tags Settings +// @Summary Export server configuration +// @Accept json +// @Produce json +// @Success 200 {object} config.Config +// @Router /settings/export_server_config [GET] func (h *Handler) ExportServerConfiguration(c echo.Context) (err error) { data := h.conf.Export() return c.Blob(http.StatusOK, echo.MIMEApplicationJSON, data) } -// @Tags Settings -// @Summary List available socks5 proxies -// @Accept json -// @Produce json -// @Success 200 {object} entity.ListAvailableProxiesResponse -// @Router /settings/list_proxies [GET] +// @Tags Settings +// @Summary List available socks5 proxies +// @Accept json +// @Produce json +// @Success 200 {object} entity.ListAvailableProxiesResponse +// @Router /settings/list_proxies [GET] func (h *Handler) ListAvailableProxies(c echo.Context) (err error) { proxies := h.socks5.ListAvailableProxies() @@ -108,13 +108,13 @@ func (h *Handler) ListAvailableProxies(c echo.Context) (err error) { return c.JSON(http.StatusOK, response) } -// @Tags Settings -// @Summary Update current proxy settings -// @Accept json -// @Produce json -// @Param body body entity.UpdateProxySettingsRequest true "Params" -// @Success 200 "OK" -// @Router /settings/set_proxy [POST] +// @Tags Settings +// @Summary Update current proxy settings +// @Accept json +// @Produce json +// @Param body body entity.UpdateProxySettingsRequest true "Params" +// @Success 200 "OK" +// @Router /settings/set_proxy [POST] func (h *Handler) UpdateProxySettings(c echo.Context) (err error) { req := entity.UpdateProxySettingsRequest{} err = c.Bind(&req) diff --git a/application.go b/application.go index 3cf1dc7b..1915754f 100644 --- a/application.go +++ b/application.go @@ -55,14 +55,14 @@ func FrontendStatic() fs.FS { return fsys } -// @title Anywherelan API -// @version 0.1 -// @description Anywherelan API +// @title Anywherelan API +// @version 0.1 +// @description Anywherelan API -// @Host localhost:8639 -// @BasePath /api/v0/ +// @Host localhost:8639 +// @BasePath /api/v0/ -//go:generate swag init --parseDependency -g application.go +//go:generate go run github.com/swaggo/swag/cmd/swag@latest init --parseDependency -g application.go //go:generate rm -f docs/docs.go docs/swagger.json type Application struct { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 0d85cfc0..941bc13b 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -4,6 +4,10 @@ definitions: properties: error: type: string + message: + description: AuthMessage is an error from Echo framework, particularly from + Basic Auth middleware + type: string type: object config.BlockedPeer: properties: @@ -16,64 +20,18 @@ definitions: description: Hex-encoded multihash representing a peer ID type: string type: object - config.Config: + config.DNSConfig: properties: - connManager: {} - connectionGater: {} - disablePing: - type: boolean - enableAutoRelay: - type: boolean - enableService: - type: boolean - forceReachability: - type: integer - insecure: + disableDNS: type: boolean - listenAddrs: - items: {} - type: array - multiaddrResolver: - $ref: '#/definitions/madns.Resolver' - muxers: - items: - $ref: '#/definitions/config.MsMuxC' - type: array - peerKey: {} - peerstore: {} - psk: - items: - type: integer - type: array - relay: - type: boolean - relayCustom: - type: boolean - relayOpts: - items: - type: integer - type: array - reporter: {} - securityTransports: - items: - $ref: '#/definitions/config.MsSecC' - type: array - staticRelays: - items: - $ref: '#/definitions/peer.AddrInfo' - type: array - throttleGlobalLimit: - type: integer - throttleInterval: - type: integer - throttlePeerLimit: - type: integer - userAgent: - description: |- - UserAgent is the identifier this node will send to other peers when - identifying itself, e.g. via the identify protocol. - - Set it via the UserAgent option function. + listenAddress: + type: string + type: object + config.HttpBasicAuthConfig: + properties: + password: + type: string + username: type: string type: object config.KnownPeer: @@ -81,6 +39,8 @@ definitions: alias: description: User provided name type: string + allowedUsingAsExitNode: + type: boolean confirmed: description: Has remote peer confirmed our invitation type: boolean @@ -105,15 +65,70 @@ definitions: peerId: description: Hex-encoded multihash representing a peer ID type: string + weAllowUsingAsExitNode: + type: boolean type: object - config.MsMuxC: + config.P2pNodeConfig: properties: - id: + autoAcceptAuthRequests: + type: boolean + bootstrapPeers: + items: + type: string + type: array + identity: type: string + ignoreDefaultBootstrapPeers: + description: With this option only BootstrapPeers from config will be used + type: boolean + listenAddresses: + items: + type: string + type: array + name: + type: string + parallelSendingStreamsCount: + type: integer + peerId: + description: Hex-encoded multihash representing a peer ID, calculated from + Identity + type: string + reconnectionIntervalSec: + type: integer + useDedicatedConnForEachStream: + type: boolean type: object - config.MsSecC: + config.SOCKS5Config: properties: - id: + listenAddress: + type: string + listenerEnabled: + type: boolean + proxyingEnabled: + description: allow using my host as proxy + type: boolean + usingPeerID: + description: peer that is set as proxy + type: string + type: object + config.UpdateConfig: + properties: + lowestPriorityChan: + type: string + trayAutoCheckEnabled: + type: boolean + trayAutoCheckInterval: + type: string + updateServerURL: + type: string + type: object + config.VPNConfig: + properties: + disableVPNInterface: + type: boolean + interfaceName: + type: string + ipNet: type: string type: object entity.AuthRequest: @@ -122,6 +137,16 @@ definitions: type: string peerID: type: string + suggestedIP: + description: SuggestedIP is a free IP address generated for this peer + type: string + type: object + entity.AvailableProxy: + properties: + peerID: + type: string + peerName: + type: string type: object entity.BandwidthDebugInfo: properties: @@ -152,10 +177,7 @@ definitions: openConnectionsCount: type: integer openStreamsCount: - type: integer - totalStreamsInbound: - type: integer - totalStreamsOutbound: + format: int64 type: integer type: object entity.DhtDebugInfo: @@ -168,10 +190,6 @@ definitions: items: type: string type: array - observedAddrs: - items: - type: string - type: array peersWithAddrsCount: type: integer reachability: @@ -180,17 +198,32 @@ definitions: - Public - Private type: string + reachableAddrs: + items: + type: string + type: array routingTable: items: $ref: '#/definitions/kbucket.PeerInfo' type: array routingTableSize: type: integer + unknownAddrs: + items: + type: string + type: array + unreachableAddrs: + items: + type: string + type: array type: object entity.FriendRequest: properties: alias: type: string + ipaddr: + description: 'optional: specific IP address for the peer' + type: string peerID: type: string required: @@ -203,6 +236,9 @@ definitions: type: string decline: type: boolean + ipaddr: + description: 'optional: specific IP address for the peer' + type: string peerID: type: string required: @@ -220,6 +256,8 @@ definitions: properties: alias: type: string + allowedUsingAsExitNode: + type: boolean confirmed: type: boolean connected: @@ -248,8 +286,19 @@ definitions: $ref: '#/definitions/entity.StatsInUnits' peerID: type: string + ping: + type: integer version: type: string + weAllowUsingAsExitNode: + type: boolean + type: object + entity.ListAvailableProxiesResponse: + properties: + proxies: + items: + $ref: '#/definitions/entity.AvailableProxy' + type: array type: object entity.P2pDebugInfo: properties: @@ -261,6 +310,10 @@ definitions: $ref: '#/definitions/entity.DhtDebugInfo' general: $ref: '#/definitions/entity.GeneralDebugInfo' + knownPeers: + items: + $ref: '#/definitions/entity.KnownPeersResponse' + type: array type: object entity.PeerIDRequest: properties: @@ -293,10 +346,27 @@ definitions: type: string serverVersion: type: string + socks5: + $ref: '#/definitions/entity.SOCKS5Info' totalBootstrapPeers: type: integer uptime: type: integer + vpn: + $ref: '#/definitions/entity.VPNInfo' + type: object + entity.SOCKS5Info: + properties: + listenAddress: + type: string + listenerEnabled: + type: boolean + proxyingEnabled: + type: boolean + usingPeerID: + type: string + usingPeerName: + type: string type: object entity.StatsInUnits: properties: @@ -318,14 +388,66 @@ definitions: properties: alias: type: string + allowUsingAsExitNode: + type: boolean domainName: type: string + ipaddr: + description: 'TODO: support ipv6' + type: string peerID: type: string required: - alias + - domainName + - ipaddr - peerID type: object + entity.UpdateProxySettingsRequest: + properties: + usingPeerID: + type: string + type: object + entity.VPNInfo: + properties: + interfaceName: + type: string + ipnet: + type: string + vpninterfaceEnabled: + type: boolean + type: object + github_com_anywherelan_awl_config.Config: + properties: + blockedPeers: + additionalProperties: + $ref: '#/definitions/config.BlockedPeer' + type: object + dns: + $ref: '#/definitions/config.DNSConfig' + httpBasicAuth: + $ref: '#/definitions/config.HttpBasicAuthConfig' + httpListenAddress: + type: string + httpListenOnAdminHost: + type: boolean + knownPeers: + additionalProperties: + $ref: '#/definitions/config.KnownPeer' + type: object + loggerLevel: + type: string + p2pNode: + $ref: '#/definitions/config.P2pNodeConfig' + socks5: + $ref: '#/definitions/config.SOCKS5Config' + update: + $ref: '#/definitions/config.UpdateConfig' + version: + type: string + vpn: + $ref: '#/definitions/config.VPNConfig' + type: object kbucket.PeerInfo: properties: addedAt: @@ -344,17 +466,19 @@ definitions: Please see the DHT docs for the definition of usefulness. type: string type: object - madns.Resolver: - type: object metrics.Stats: properties: rateIn: + format: float64 type: number rateOut: + format: float64 type: number totalIn: + format: int64 type: integer totalOut: + format: int64 type: integer type: object p2p.BootstrapPeerDebugInfo: @@ -365,6 +489,8 @@ definitions: type: array error: type: string + ping: + type: string type: object p2p.ConnectionInfo: properties: @@ -385,14 +511,6 @@ definitions: transient: type: boolean type: object - peer.AddrInfo: - properties: - addrs: - items: {} - type: array - id: - type: string - type: object host: localhost:8639 info: contact: {} @@ -629,8 +747,22 @@ paths: "200": description: OK schema: - $ref: '#/definitions/config.Config' + $ref: '#/definitions/github_com_anywherelan_awl_config.Config' summary: Export server configuration + tags: + - Settings + /settings/list_proxies: + get: + consumes: + - application/json + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/entity.ListAvailableProxiesResponse' + summary: List available socks5 proxies tags: - Settings /settings/peer_info: @@ -645,6 +777,25 @@ paths: schema: $ref: '#/definitions/entity.PeerInfo' summary: Get my peer info + tags: + - Settings + /settings/set_proxy: + post: + consumes: + - application/json + parameters: + - description: Params + in: body + name: body + required: true + schema: + $ref: '#/definitions/entity.UpdateProxySettingsRequest' + produces: + - application/json + responses: + "200": + description: OK + summary: Update current proxy settings tags: - Settings /settings/update: diff --git a/p2p/metrics.go b/p2p/metrics.go index 39145d7b..3f5d25b2 100644 --- a/p2p/metrics.go +++ b/p2p/metrics.go @@ -6,7 +6,7 @@ import ( "strings" "time" - "github.com/libp2p/go-libp2p-kbucket" + kbucket "github.com/libp2p/go-libp2p-kbucket" "github.com/libp2p/go-libp2p/core/metrics" "github.com/libp2p/go-libp2p/core/network" "github.com/libp2p/go-libp2p/core/peer" @@ -47,7 +47,7 @@ type ConnectionInfo struct { type BootstrapPeerDebugInfo struct { Error string `json:",omitempty"` Connections []string `json:",omitempty"` - Ping Duration `json:",omitempty"` + Ping Duration `json:",omitempty" swaggertype:"string"` } func (p *P2p) Uptime() time.Duration {