Rework doc v1

Makefile

@@ -43,7 +43,7 @@ watch-relayproxy: ## Launch the relay proxy in watch mode.
 
 swagger: ## Build swagger documentation
 	$(GOCMD) install github.com/swaggo/swag/cmd/swag@latest
-	cd cmd/relayproxy && swag init --parseDependency --parseDepth 2
+	cd cmd/relayproxy && swag init --markdownFiles docs
 
 ## Test:
 test: ## Run the tests of the project

README.md

@@ -58,8 +58,8 @@ Originally GO Feature Flag was built to be a GOlang only library, but it limits
 To be compatible with more language we have implemented the [GO Feature Flag Relay Proxy](https://github.com/thomaspoignant/go-feature-flag-relay-proxy).
 It is a service you can host that provides an API to evaluate your flags, you can call it using HTTP to get your variation.
 
-Since we believe in standardization we are also implementing [Open-feature](https://github.com/open-feature) providers to interact with this API in the language of your choice.  
-_(Open-feature is still at an early stage, so not all languages are supported and expect some changes in the future)_
+Since we believe in standardization we are also implementing [OpenFeature](https://github.com/open-feature) providers to interact with this API in the language of your choice.  
+_(OpenFeature is still at an early stage, so not all languages are supported and expect some changes in the future)_
 
 ## Getting started
 First, you need to initialize the `ffclient` with the location of your backend file.

cmd/relayproxy/controller/all_flags.go

@@ -19,18 +19,21 @@ func NewAllFlags(goFF *ffclient.GoFeatureFlag) Controller {
 }
 
 // Handler is the entry point for the allFlags endpoint
-// @Summary      allflags returns all the flag for a specific user.
-// @Description  allflags returns all the flag for a specific user.
-// @Tags         flags
+// @Summary      All flags variations for a user
+// @Description  Making a **POST** request to the URL `/v1/allflags` will give you the values of all the flags for
+// @Description this user.
+// @Description
+// @Description To get a variation you should provide information about the user.
+// @Description For that you should provide some user information in JSON in the request body.
 // @Produce      json
 // @Accept			 json
-// @Param 			 data body model.RelayProxyRequest true "Payload of the user we want to challenge against the flag."
+// @Param 			 data body model.AllFlagRequest true "Payload of the user we want to challenge against the flag."
 // @Success      200  {object}   modeldocs.AllFlags "Success"
-// @Failure 		 400 {object} modeldocs.HTTPError "Bad Request"
-// @Failure      500 {object} modeldocs.HTTPError "Internal server error"
+// @Failure 		 400 {object} modeldocs.HTTPErrorDoc "Bad Request"
+// @Failure      500 {object} modeldocs.HTTPErrorDoc "Internal server error"
 // @Router       /v1/allflags [post]
 func (h *allFlags) Handler(c echo.Context) error {
-	reqBody := new(model.RelayProxyRequest)
+	reqBody := new(model.AllFlagRequest)
 	if err := c.Bind(reqBody); err != nil {
 		return err
 	}

cmd/relayproxy/controller/flag_eval.go

@@ -20,28 +20,33 @@ func NewFlagEval(goFF *ffclient.GoFeatureFlag) Controller {
 }
 
 // Handler is the entry point for the flag eval endpoint
-// @Summary      Evaluate the users with the corresponding flag and return the value for the user.
-// @Description  Evaluate the users with the corresponding flag and return the value for the user.
-// @Description  Note that you will always have a usable value in the response, you can use the field failed to know if
-// @Description  an issue has occurred during the validation of the flag, in that case the value returned will be the
-// @Description  default value.
-// @Tags         flags
+// @Summary     Evaluate a feature flag
+// @Description Making a **POST** request to the URL `/v1/feature/<your_flag_name>/eval` will give you the value of the
+// @Description flag for this user.
+// @Description
+// @Description To get a variation you should provide information about the user:
+// @Description - User information in JSON in the request body.
+// @Description - A default value in case there is an error while evaluating the flag.
+// @Description
+// @Description Note that you will always have a usable value in the response, you can use the field `failed` to know if
+// @Description an issue has occurred during the validation of the flag, in that case the value returned will be the
+// @Description default value.
 // @Produce      json
 // @Accept			 json
-// @Param 			 data body model.RelayProxyRequest true "Payload of the user we want to get all the flags from."
+// @Param 			 data body model.EvalFlagRequest true "Payload of the user we want to get all the flags from."
 // @Param        flag_key path string true "Name of your feature flag"
-// @Success      200  {object}   model.FlagEval "Success"
-// @Failure 		 400 {object} modeldocs.HTTPError "Bad Request"
-// @Failure      500 {object} modeldocs.HTTPError "Internal server error"
+// @Success      200  {object}   modeldocs.EvalFlagDoc "Success"
+// @Failure 		 400 {object} modeldocs.HTTPErrorDoc "Bad Request"
+// @Failure      500 {object} modeldocs.HTTPErrorDoc "Internal server error"
 // @Router       /v1/feature/{flag_key}/eval [post]
 func (h *flagEval) Handler(c echo.Context) error {
-	reqBody := new(model.RelayProxyRequest)
+	reqBody := new(model.EvalFlagRequest)
 	if err := c.Bind(reqBody); err != nil {
 		return err
 	}
 
 	// validation that we have a reqBody key
-	if err := assertRequest(reqBody); err != nil {
+	if err := assertRequest(&reqBody.AllFlagRequest); err != nil {
 		return err
 	}
 	goFFUser, err := userRequestToUser(reqBody.User)

cmd/relayproxy/controller/health.go

@@ -19,12 +19,15 @@ func NewHealth(monitoring service.Monitoring) Controller {
 }
 
 // Handler is the entry point for this API
-// @Summary      Health, status endpoint
-// @Description  Health is the status endpoint of the relay proxy, you should call it to check if the relay proxy is up.
-// @Tags         monitoring
+// @Summary      Health
+// @Description Making a **GET** request to the URL path `/health` will tell you if the relay proxy is ready to serve
+// @Description traffic.
+// @Description
+// @Description This is useful especially for loadbalancer to know that they can send traffic to the service.
 // @Produce      json
 // @Success      200  {object}   model.HealthResponse
 // @Router       /health [get]
+//
 func (h *health) Handler(c echo.Context) error {
 	return c.JSON(http.StatusOK, h.monitoringService.Health())
 }

cmd/relayproxy/controller/info.go

@@ -18,9 +18,12 @@ func NewInfo(monitoring service.Monitoring) Controller {
 }
 
 // Handler is the entry point for the Info API
-// @Summary      Info, give information about the instance of go-feature-flag relay proxy
-// @Description  Info, give information about the instance of go-feature-flag relay proxy
-// @Tags         monitoring
+// @Summary      Info
+// @Description  Making a **GET** request to the URL path `/info` will tell give you information about the actual state
+// @Description  of the relay proxy.
+// @Description
+// @Description	As of Today the level of information is small be we can improve this endpoint to returns more
+// @Description information.
 // @Produce      json
 // @Success      200  {object}   model.InfoResponse
 // @Router       /info [get]

cmd/relayproxy/controller/utils.go

@@ -10,7 +10,7 @@ import (
 )
 
 // assertRequest is the function which validates the request, if not valid an echo.HTTPError is return.
-func assertRequest(u *model.RelayProxyRequest) *echo.HTTPError {
+func assertRequest(u *model.AllFlagRequest) *echo.HTTPError {
 	if u == nil || u.User == nil {
 		return echo.NewHTTPError(http.StatusBadRequest, "assertRequest: impossible to find user in request")
 	}
@@ -25,7 +25,7 @@ func assertUserKey(userKey string) *echo.HTTPError {
 	return nil
 }
 
-// userRequestToUser convert a user from the request model.RelayProxyRequest to a go-feature-flag ffuser.User
+// userRequestToUser convert a user from the request model.AllFlagRequest to a go-feature-flag ffuser.User
 func userRequestToUser(u *model.UserRequest) (ffuser.User, error) {
 	if u == nil {
 		return ffuser.User{}, fmt.Errorf("userRequestToUser: impossible to convert user, userRequest nil")

cmd/relayproxy/docs/api.md

@@ -0,0 +1,6 @@
+# Introduction
+
+This API is documented in **OpenAPI format** and describe the REST API of the **GO Feature Flag relay proxy**.
+
+The relay proxy is a component to evaluate your feature flags remotely when using **GO Feature Flag**.  
+This API is mostly used by all the OpenFeature providers.