add category/icon to public api publisher (#122)

* add category/icon to public api publisher

* merge file and defaults

* fix comment

cmd/publisher/README.md

@@ -1,8 +1,26 @@
 # API Publisher
 
-This scripts takes open api specs that are generated in each folder by `make proto` (see `api-users.json` and similar in each folder), and existing `README.md` and published the API.
+The public api publisher for Micro services
 
-The readmes are taken verbatim and autogenerated client call examples are appended to them to produce an output readme, so there is no need to write curl or micro cli or any other examples. Focus on the describing the service in the readmes.
+## Overview
+
+The API publisher assumes a few things:
+
+- Your service name is the directory of the service
+- You have a `README.md` file we take as description
+- You have a `make api` command to generate a `api-{service}.json` for the OpenAPI spec
+- You optionally have a `publicapi.json` file to define extra info such a category, icon, etc
+- You optionally have a `examples.json` file to separately define usage examples
+- You optionaly have a `pricing.json` file to separately define pricing information
+
+All these are combined to produce a Public API.
+
+## Readme
+
+The readmes are taken verbatim. Everything before the newline is used as a short excerpt. Examples are appended to your API 
+tab if they exist so no need to add random examples, curls, etc to the readme. Focus on describing the service in brevity.
+
+## Comments
 
 Some rules on how to write protos so they nicely appear in the output of this script:
 

cmd/publisher/main.go

@@ -16,16 +16,18 @@ import (
 	"github.com/getkin/kin-openapi/openapi3"
 )
 
-func publishAPI(service, readme, openapiJSON, examplesJSON string, pricing map[string]int64) error {
-	client := &http.Client{}
+type PublicAPI struct {
+	Name         string           `json:"name"`
+	Category     string           `json:"category,omitempty"`
+	Description  string           `json:"description"`
+	Icon         string           `json:"icon,omitempty"`
+	OpenAPIJson  string           `json:"open_api_json"`
+	Pricing      map[string]int64 `json:"pricing,omitempty"`
+	ExamplesJson string           `json:"examples_json,omitempty"`
+}
 
-	apiSpec := map[string]interface{}{
-		"name":          service,
-		"description":   readme,
-		"open_api_json": openapiJSON,
-		"pricing":       pricing,
-		"examples_json": examplesJSON,
-	}
+func publishAPI(apiSpec *PublicAPI) error {
+	client := &http.Client{}
 
 	//Encode the data
 	postBody, _ := json.Marshal(map[string]interface{}{
@@ -100,24 +102,54 @@ func main() {
 					os.Exit(1)
 				}
 			}
+
 			spec := &openapi3.Swagger{}
-			err = json.Unmarshal(js, &spec)
-			if err != nil {
+
+			// we have to read an openapi spec otherwise we can't publish
+			if err := json.Unmarshal(js, &spec); err != nil {
 				fmt.Println("Failed to unmarshal", err)
 				os.Exit(1)
 			}
 
-			// not every service has examples
-			examples, _ := ioutil.ReadFile(filepath.Join(serviceDir, "examples.json"))
+			// define the default public api values
+			var publicApi *PublicAPI
 
-			pricingRaw, _ := ioutil.ReadFile(filepath.Join(serviceDir, "pricing.json"))
-			pricing := map[string]int64{}
-			if len(pricingRaw) > 0 {
-				json.Unmarshal(pricingRaw, &pricing)
+			// if we find a public api definition we load it
+			if b, err := ioutil.ReadFile(filepath.Join(serviceDir, "publicapi.json")); err == nil {
+				// unpack the info if we read the file
+				json.Unmarshal(b, &publicApi)
 			}
 
-			err = publishAPI(serviceName, string(dat), string(js), string(examples), pricing)
-			if err != nil {
+			// If we didn't get the default info from a file, populate it
+			if publicApi.Name == "" {
+				publicApi.Name = serviceName
+			}
+			if publicApi.Description == "" {
+				publicApi.Description = string(dat)
+			}
+			if publicApi.OpenAPIJson == "" {
+				publicApi.OpenAPIJson = string(js)
+			}
+
+			// load the examples if they exist
+			if examples, err := ioutil.ReadFile(filepath.Join(serviceDir, "examples.json")); err == nil {
+				if len(examples) > 0 {
+					publicApi.ExamplesJson = string(examples)
+				}
+			}
+
+			// load the separate pricing if it exists
+			if pricingRaw, err := ioutil.ReadFile(filepath.Join(serviceDir, "pricing.json")); err == nil {
+				pricing := map[string]int64{}
+				// unmarshal the pricing info
+				if len(pricingRaw) > 0 {
+					json.Unmarshal(pricingRaw, &pricing)
+					publicApi.Pricing = pricing
+				}
+			}
+
+			// publish the api
+			if err := publishAPI(publicApi); err != nil {
 				fmt.Println("Failed to save data to publicapi service", err)
 				os.Exit(1)
 			}