totole/services
1
0
Fork 0
mirror of https://github.com/kevin-DL/services.git synced 2026-01-22 15:25:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* add category/icon to public api publisher

* merge file and defaults

* fix comment
This commit is contained in:
Asim Aslam
2021-05-23 19:48:38 +01:00
committed by GitHub
parent 49db4bc81b
commit 538c5c48a9
2 changed files with 71 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
cmd/publisher/README.md
View File

@@ -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: