|
1 | | -# Bluecore APIs OpenAPI Config Files |
| 1 | +# Bluecore OpenAPI Docs |
| 2 | +This repository contains the files necessary to configure Bluecore API docs following Open API 3.0 specifications. |
2 | 3 |
|
3 | | -This repository contains the code that supports serving the Bluecore Transactional API documentation using Redoc. |
| 4 | +Currently, the only the [Bluecore Transactional API Docs](https://www.bluecore.com/transactional-api-docs/) are live. |
| 5 | + |
| 6 | + |
| 7 | +## Config Files |
| 8 | +OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: |
| 9 | + |
| 10 | +- Available endpoints (e.g. `/users`) and operations on each endpoint (`GET /users`, `POST /users`, etc.) |
| 11 | +- Operation parameters Input and output for each operation |
| 12 | +- Authentication methods |
| 13 | +- Contact information, license, terms of use and other information. |
| 14 | + |
| 15 | +API specifications are written in YAML. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: [OpenAPI 3.0 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) |
| 16 | + |
| 17 | + |
| 18 | +## Redoc |
| 19 | +The API specification YAML file is parsed by [Redoc](https://github.com/Redocly/redoc) - an open-source tool that generates the front-end components for our API docs. |
| 20 | + |
| 21 | +To render API documentation using Redoc, all you need to do is add Redoc's `<script>` tag on the page, along with a `<redoc>` tag pointing to the API specification YAML file. |
| 22 | + |
| 23 | +e.g. HTML |
| 24 | +``` |
| 25 | + <body> |
| 26 | + <redoc spec-url='https://storage.googleapis.com/download/storage/v1/b/bluecore-openapi-docs/o/transactional-api%2Ftransactional_api.yaml?alt=media' hide-download-button></redoc> |
| 27 | +
|
| 28 | + <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> |
| 29 | + </body> |
| 30 | +``` |
| 31 | + |
| 32 | + |
| 33 | +## Hosting |
| 34 | +Currently, docs are hosted on `www.bluecore.com/`, where our public-facing marketing pages live. API Docs are added as custom pages on Bluecore's Wordpress set up. |
| 35 | + |
| 36 | +We chose to host the API Docs on Wordpress mainly because this was a solution that was free and quick to stand up. It is not a perfect solution and the recommendation would be to look for a better hosting solution for Bluecore's public API documentation. |
| 37 | + |
| 38 | + |
| 39 | +## Deployment |
| 40 | +Whenever changes are merged into `master` on GitHub, CircleCI will take the files in `./apis` and upload them to a public Google Cloud Storage bucket (specifically [bluecore-openapi-docs](https://console.cloud.google.com/storage/browser/bluecore-openapi-docs;tab=objects?forceOnBucketsSortingFiltering=false&project=triggeredmail&prefix=&forceOnObjectsSortingFiltering=false)). |
| 41 | + |
| 42 | +The corresponding Wordpress page pulls the config YAML file from Google Cloud Storage. |
| 43 | +E.g. from the Wordpress set up of the Bluecore Transactional API Docs |
| 44 | +``` |
| 45 | +<!-- YAML config file --> |
| 46 | +<redoc spec-url='https://storage.googleapis.com/download/storage/v1/b/bluecore-openapi-docs/o/config_files%2Ftransactional_api.yaml?alt=media' hide-download-button></redoc> |
| 47 | +
|
| 48 | +<!-- Redoc script --> |
| 49 | +<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> |
| 50 | +``` |
| 51 | + |
| 52 | +When any changes are merged, all of the files in `./apis` will be deployed to GCS, and those changes will be reflected the next time the browser is loaded. |
| 53 | + |
| 54 | + |
| 55 | +## Next Steps |
| 56 | +Short Term: |
| 57 | +- Gather feedback from internal users |
| 58 | +- Migrate the Bluecore Transactional API docs on KB to the new doc |
| 59 | + |
| 60 | +Long Term: |
| 61 | +- Identify other external APIs that need updated API docs |
| 62 | +- Identify a better enterprise hosting solution for docs. The current solution of hosting our API docs on the marketing website is not ideal. There are limitations on Wordpress, such as URL structure for when we push up multiple pages, unconfigurable links in the nav bar and marketing bot widgets, etc. |
| 63 | + |
| 64 | + |
| 65 | +## How Do I Add New API Doc Pages? |
| 66 | +Follow the steps below to create new docs for another Bluecore API: |
| 67 | + |
| 68 | +#### Make a Config File |
| 69 | +Make a new directory in `./apis/` with the name of the API (e.g. `mobile-events-api-v1`). |
| 70 | +In that folder, create a YAML config file following Open API 3.0 specifications. |
| 71 | +You can also add a CSS file for custom styling for this page. |
| 72 | + |
| 73 | +To view locally, edit the `<redoc>` tag in `./index.html` to reference your new config file: |
| 74 | +``` |
| 75 | +<redoc spec-url='./apis/mobile-events-api-v1/config.yaml' hide-download-button></redoc> |
| 76 | +``` |
| 77 | + |
| 78 | +Then run `yarn open-redoc` from the command line. This will open up a live server on localhost using the contents of `index.html`. Any saved changes will cause the page to re-load with the new content. |
| 79 | + |
| 80 | + |
| 81 | +#### Set Up the Wordpress Page |
| 82 | +In Wordpress, add a new page on using the "API Docs" Wordpress template. You can set the page's URL to `your-api-name`. |
| 83 | +You will need admin access on Wordpress to complete this step (contact the Marketing team if you need access). |
| 84 | + |
| 85 | +The page contents should include the `<script>` tag to load Redoc on the page along with the `<redoc>` tag that references your API's YAML config file. You can also include a `<link>` tag to load custom CSS. |
| 86 | + |
| 87 | +``` |
| 88 | +<!-- CSS --> |
| 89 | +<link type="text/css" rel="stylesheet" href="https://storage.googleapis.com/download/storage/v1/b/bluecore-openapi-docs/o/css_files%2Ftransactional_api.css?alt=media"> |
| 90 | +
|
| 91 | +<!-- YAML config file --> |
| 92 | +<redoc spec-url='https://storage.googleapis.com/download/storage/v1/b/bluecore-openapi-docs/o/config_files%2Ftransactional_api.yaml?alt=media' hide-download-button></redoc> |
| 93 | +
|
| 94 | +<!-- Redoc script --> |
| 95 | +<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> |
| 96 | +``` |
| 97 | + |
| 98 | +The `href` and `spec-url`s follow Google Cloud Storage's URL format for [downloading Cloud Storage objects](https://cloud.google.com/storage/docs/downloading-objects). |
| 99 | + |
| 100 | + |
| 101 | +#### Deploy to GCS |
| 102 | +Merge to master and verify your new docs have been deployed by going to [Google Cloud Storage](https://console.cloud.google.com/storage/browser/bluecore-openapi-docs;tab=objects?forceOnBucketsSortingFiltering=false&project=triggeredmail&prefix=&forceOnObjectsSortingFiltering=false) and looking for your files. |
| 103 | + |
| 104 | +Finally, go to the live page on www.bluecore.com/your-api-here and check the live version of your docs! |
0 commit comments