API Docs: Fix wrong API reponse types, add authorization header

api/api.go

@@ -48,7 +48,9 @@ import (
 //	@host		api-dev.vocdoni.net
 //	@BasePath	/v2
 
-//	@securityDefinitions.basic	BasicAuth
+//	@securityDefinitions.apikey	ApiKeyAuth
+//	@in header
+//	@name Authorization
 
 // MaxPageSize defines the maximum number of results returned by the paginated endpoints
 const MaxPageSize = 10

api/censuses.go

@@ -213,7 +213,7 @@ func (a *API) enableCensusHandlers() error {
 //	@Tags					Censuses
 //	@Accept					json
 //	@Produce				json
-//	@Security				BasicAuth
+//	@Security				ApiKeyAuth
 //	@Param					type	path		string	true	"Census type"	Enums(weighted,zkweighted,csp)
 //	@Success				200		{object}	object{censusId=string}
 //	@Router					/censuses/{type} [post]
@@ -250,7 +250,7 @@ func (a *API) censusCreateHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCont
 //	@Tags					Censuses
 //	@Accept					json
 //	@Produce				json
-//	@Security				BasicAuth
+//	@Security				ApiKeyAuth
 //	@Param					censusID	path	string				true	"Census id"
 //	@Param					transaction	body	CensusParticipants	true	"PublicKey - weight array "
 //	@Success				200			"(empty body)"
@@ -408,15 +408,15 @@ func (a *API) censusRootHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext)
 
 // censusDumpHandler
 //
-//	@Summary		Export census
-//	@Description	Export census to JSON format. Requires Bearer token
-//	@Tags			Censuses
-//	@Accept			json
-//	@Produce		json
-//	@Security		BasicAuth
-//	@Param			censusID	path		string	true	"Census id"
-//	@Success		200			{object}	censusdb.CensusDump
-//	@Router			/censuses/{censusID}/export [get]
+//		@Summary		Export census
+//		@Description	Export census to JSON format. Requires Bearer token
+//		@Tags			Censuses
+//		@Security		ApiKeyAuth
+//		@Accept			json
+//		@Produce		json
+//		@Param			censusID path string true "Census id"
+//	 @Success		200			{object}	censusdb.CensusDump
+//	 @Router			/censuses/{censusID}/export [get]
 func (a *API) censusDumpHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	token, err := uuid.Parse(msg.AuthToken)
 	if err != nil {
@@ -461,7 +461,7 @@ func (a *API) censusDumpHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContex
 //	@Tags			Censuses
 //	@Accept			json
 //	@Produce		json
-//	@Security		BasicAuth
+//	@Security		ApiKeyAuth
 //	@Param			censusID	path	string	true	"Census id"
 //	@Success		200			"(empty body)"
 //	@Router			/censuses/{censusID}/import [post]
@@ -587,17 +587,18 @@ func (a *API) censusSizeHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext)
 
 // censusDeleteHandler
 //
-//	@Summary		Delete census
-//	@Description	Delete unpublished census (not on the storage yet). See [publish census](census-publish)\n
-//	@Description	- Requires Bearer token
-//	@Description	- Deletes a census from the server storage
-//	@Description	- Published census cannot be deleted
-//	@Tags			Censuses
-//	@Accept			json
-//	@Produce		json
-//	@Param			censusID	path	string	true	"Census id"
-//	@Success		200			"(empty body)"
-//	@Router			/censuses/{censusID} [delete]
+//		@Summary		Delete census
+//		@Description	Delete unpublished census (not on the storage yet). See [publish census](census-publish)\n
+//		@Description	- Requires Bearer token
+//		@Description	- Deletes a census from the server storage
+//		@Description	- Published census cannot be deleted
+//		@Tags			Censuses
+//		@Accept			json
+//		@Produce		json
+//		@Param			censusID	path	string	true	"Census id"
+//		@Success		200			"(empty body)"
+//		@Security		ApiKeyAuth
+//	 @Router			/censuses/{censusID} [delete]
 func (a *API) censusDeleteHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	token, err := uuid.Parse(msg.AuthToken)
 	if err != nil {
@@ -628,7 +629,7 @@ func (a *API) censusDeleteHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCont
 //	@Tags					Censuses
 //	@Accept					json
 //	@Produce				json
-//	@Security				BasicAuth
+//	@Security				ApiKeyAuth
 //	@Success				200			{object}	object{census=object{censusID=string,uri=string}}	"It return published censusID and the ipfs uri where its uploaded"
 //	@Param					censusID	path		string												true	"Census id"
 //	@Router					/censuses/{censusID}/publish [post]
@@ -816,7 +817,7 @@ func (a *API) censusPublishCheckHandler(_ *apirest.APIdata, ctx *httprouter.HTTP
 //	@Tags					Censuses
 //	@Accept					json
 //	@Produce				json
-//	@Security				BasicAuth
+//	@Security				ApiKeyAuth
 //	@Param					censusID	path		string											true	"Census id"
 //	@Param					key			path		string											true	"Key to proof"
 //	@Success				200			{object}	object{weight=number,proof=string,value=string}	"where proof is Merkle tree siblings and value is Merkle tree leaf value"
@@ -951,13 +952,14 @@ func (a *API) censusVerifyHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCont
 
 // censusListHandler
 //
-//	@Summary		List all census references
-//	@Description	List all census references. Requires Admin Bearer token.
-//	@Tags			Censuses
-//	@Accept			json
-//	@Produce		json
-//	@Success		200	{object}	object{valid=bool}
-//	@Router			/censuses/list/ [get]
+//		@Summary		List all census references
+//		@Description	List all census references. Requires Admin Bearer token.
+//		@Tags			Censuses
+//	 @Security       ApiKeyAuth
+//		@Accept			json
+//		@Produce		json
+//		@Success		200	{object}	[]censusdb.CensusList
+//		@Router			/censuses/list [get]
 func (a *API) censusListHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	list, err := a.censusdb.List()
 	if err != nil {
@@ -976,9 +978,10 @@ func (a *API) censusListHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext)
 //	@Description	Export the whole census database to a JSON file. Requires Admin Bearer token.
 //	@Tags			Censuses
 //	@Accept			json
+//	@Security		ApiKeyAuth
 //	@Produce		json
 //	@Param			ipfs	path		string	true	"Export to IPFS. Blank to return the JSON file"
-//	@Success		200		{object}	object{valid=bool}
+//	@Success		200		{object}	object{uri=string}
 //	@Router			/censuses/export/{ipfs} [get]
 func (a *API) censusExportDBHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	isIPFSExport := strings.HasSuffix(ctx.Request.URL.Path, "ipfs")
@@ -1011,7 +1014,7 @@ func (a *API) censusExportDBHandler(_ *apirest.APIdata, ctx *httprouter.HTTPCont
 //	@Tags			Censuses
 //	@Accept			json
 //	@Produce		json
-//	@Success		200	{object}	object{valid=bool}
+//	@Success		200	 "(empty body)"
 //	@Router			/censuses/import/{ipfscid} [post]
 func (a *API) censusImportDBHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	ipfscid := ctx.URLParam("ipfscid")

api/docs/README.md

@@ -23,7 +23,7 @@ The `Accounts` tag refer to the namespace where the endpoint behalf, see
 //    @Param            address    path        string    true    "Account address"
 // For body objects 
 //    @Param                    transaction    body        object{txPayload=string,metadata=string}    true    "Transaction payload and metadata object encoded using base64 "
-//    @Security                BasicAuth
+//    @Security                ApiKeyAuth
 // If bearer token is needed (for some census ops for example)
 ```
 

api/docs/models/models.go

@@ -46,7 +46,7 @@ func ElectionListByStatusHandler() {
 //	@Tags					Censuses
 //	@Accept					json
 //	@Produce				json
-//	@Security				BasicAuth
+//	@Security				ApiKeyAuth
 //	@Success				200			{object}	object{census=object{censusID=string,uri=string}}	"It return published censusID and the ipfs uri where its uploaded"
 //	@Param					censusID	path		string												true	"Census id"
 //	@Param					root		path		string												true	"Specific root where to publish the census. Not required"

api/elections.go

@@ -132,7 +132,7 @@ func (a *API) enableElectionHandlers() error {
 //	@Accept			json
 //	@Produce		json
 //	@Param			page	path		number	true	"Page "
-//	@Success		200		{object}	ElectionSummary
+//	@Success		200		{object}	object{elections=[]ElectionSummary}
 //	@Router			/elections/page/{page} [get]
 func (a *API) electionFullListHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	page := 0
@@ -336,7 +336,7 @@ func (a *API) electionKeysHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContex
 //	@Produce		json
 //	@Param			electionID	path		string	true	"Election id"
 //	@Param			page		path		number	true	"Page "
-//	@Success		200			{object}	Vote
+//	@Success		200			{object}	object{votes=[]Vote}
 //	@Router			/elections/{electionID}/votes/page/{page} [get]
 func (a *API) electionVotesHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	electionID, err := hex.DecodeString(util.TrimHex(ctx.URLParam("electionID")))
@@ -621,7 +621,7 @@ func getElection(electionID []byte, vs *state.State) (*models.Process, error) {
 //	@Produce				json
 //	@Param					page		path		number			true	"Page to paginate"
 //	@Param					transaction	body		ElectionFilter	true	"Filtered by partial organizationID, partial processID, process status and with results available or not"
-//	@Success				200			{object}	ElectionSummary
+//	@Success				200			{object}	object{elections=[]ElectionSummary}
 //	@Router					/elections/filter/page/{page} [post]
 func (a *API) electionFilterPaginatedHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	// get organizationId from the request body

api/wallet.go

@@ -198,7 +198,7 @@ func (a *API) walletAddHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext)
 //
 //	@Summary		Set wallet account
 //	@Description	Set a new account. Needed the bearer token associated the account.
-//	@Security		BasicAuth
+//	@Security		ApiKeyAuth
 //	@Tags			Wallet
 //	@Accept			json
 //	@Produce		json
@@ -245,7 +245,7 @@ func (a *API) walletCreateHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCont
 //
 //	@Summary		Transfer tokens
 //	@Description	Transfer balance to another account. Needed the bearer token associated the account.
-//	@Security		BasicAuth
+//	@Security		ApiKeyAuth
 //	@Tags			Wallet
 //	@Accept			json
 //	@Produce		json
@@ -303,15 +303,16 @@ func (a *API) walletTransferHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCo
 
 // walletElectionHandler
 //
-//	@Summary		Create election for wallet
-//	@Description	Creates an election. Requires the bearer token of the account you want to create the election.
-//	@Security		BasicAuth
-//	@Tags			Wallet
-//	@Accept			json
-//	@Produce		json
-//	@Param			description	body		ElectionDescription	true	"Election description"
-//	@Success		200			{object}	Transaction
-//	@Router			/wallet/election [post]
+//		@Summary		Create election for wallet
+//		@Description	Creates an election. Requires the bearer token of the account you want to create the election.
+//		@Security		ApiKeyAuth
+//	 	@Param 			Auth-Token header string true "Bearer "
+//		@Tags			Wallet
+//		@Accept			json
+//		@Produce		json
+//		@Param			description	body		ElectionDescription	true	"Election description"
+//		@Success		200			{object}	Transaction
+//		@Router			/wallet/election [post]
 func (a *API) walletElectionHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	wallet, err := a.walletFromToken(msg.AuthToken)
 	if err != nil {

go.mod

@@ -1,6 +1,6 @@
 module go.vocdoni.io/dvote
 
-go 1.22.0
+go 1.22.4
 
 // For testing purposes
 // replace go.vocdoni.io/proto => ../dvote-protobuf
@@ -56,6 +56,7 @@ require (
 	github.com/rs/zerolog v1.31.0
 	github.com/spf13/pflag v1.0.5
 	github.com/spf13/viper v1.18.2
+	github.com/swaggo/swag v1.16.3
 	github.com/syndtr/goleveldb v1.0.1-0.20220614013038-64ee5596c38a
 	github.com/vocdoni/storage-proofs-eth-go v0.1.6
 	go.mongodb.org/mongo-driver v1.12.1
@@ -73,8 +74,11 @@ require (
 	github.com/AndreasBriese/bbloom v0.0.0-20190825152654-46b345b51c96 // indirect
 	github.com/DataDog/zstd v1.5.2 // indirect
 	github.com/Jorropo/jsync v1.0.1 // indirect
+	github.com/KyleBanks/depth v1.2.1 // indirect
 	github.com/Microsoft/go-winio v0.6.1 // indirect
 	github.com/OneOfOne/xxhash v1.2.5 // indirect
+	github.com/PuerkitoBio/purell v1.1.1 // indirect
+	github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578 // indirect
 	github.com/alecthomas/units v0.0.0-20231202071711-9a357b53e9c9 // indirect
 	github.com/alexbrainman/goissue34681 v0.0.0-20191006012335-3fc7a47baff5 // indirect
 	github.com/benbjohnson/clock v1.3.5 // indirect
@@ -130,6 +134,10 @@ require (
 	github.com/go-logr/logr v1.4.1 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-ole/go-ole v1.3.0 // indirect
+	github.com/go-openapi/jsonpointer v0.19.5 // indirect
+	github.com/go-openapi/jsonreference v0.19.6 // indirect
+	github.com/go-openapi/spec v0.20.4 // indirect
+	github.com/go-openapi/swag v0.19.15 // indirect
 	github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
 	github.com/gofrs/flock v0.8.1 // indirect
@@ -190,6 +198,7 @@ require (
 	github.com/jbenet/go-temp-err-catcher v0.1.0 // indirect
 	github.com/jbenet/goprocess v0.1.4 // indirect
 	github.com/jmhodges/levigo v1.0.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
 	github.com/koron/go-ssdp v0.0.4 // indirect
 	github.com/kr/pretty v0.3.1 // indirect
@@ -215,6 +224,7 @@ require (
 	github.com/libp2p/zeroconf/v2 v2.2.0 // indirect
 	github.com/linxGnu/grocksdb v1.8.6 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/marten-seemann/tcp v0.0.0-20210406111302-dfbc87cc63fd // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect