{"id":23065879,"url":"https://github.com/tidepool-org/tidepoolapi","last_synced_at":"2025-08-15T11:32:22.430Z","repository":{"id":66274375,"uuid":"239433889","full_name":"tidepool-org/TidepoolApi","owner":"tidepool-org","description":"Tidepool APIs documented with OpenAPI v3, for schema validation and client and server code generation.","archived":false,"fork":false,"pushed_at":"2024-10-23T15:50:03.000Z","size":5137,"stargazers_count":3,"open_issues_count":9,"forks_count":1,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-23T20:53:05.910Z","etag":null,"topics":["api","openapi","openapi3"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tidepool-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-10T05:20:54.000Z","updated_at":"2024-10-23T15:47:04.000Z","dependencies_parsed_at":"2023-10-17T17:31:43.334Z","dependency_job_id":"f2532a35-d003-4d25-8b30-5e5a19955650","html_url":"https://github.com/tidepool-org/TidepoolApi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidepool-org%2FTidepoolApi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidepool-org%2FTidepoolApi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidepool-org%2FTidepoolApi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tidepool-org%2FTidepoolApi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tidepool-org","download_url":"https://codeload.github.com/tidepool-org/TidepoolApi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229911004,"owners_count":18143229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","openapi","openapi3"],"created_at":"2024-12-16T05:10:21.969Z","updated_at":"2024-12-16T05:10:22.461Z","avatar_url":"https://github.com/tidepool-org.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TidepoolApi \n\n![Tidepool Logo](./assets/images/Tidepool_Logo_Dark_Large.png)\n\n[![publish](https://github.com/tidepool-org/TidepoolApi/actions/workflows/check-and-publish.yml/badge.svg?branch=master)](https://github.com/tidepool-org/TidepoolApi/actions/workflows/check-and-publish.yml)\n\nThis repository contains Tidepool Platform API documentation in [OpenAPI v3](https://www.openapis.org/) format with additional narrative content in [Stoplight-flavored](https://meta.stoplight.io/docs/studio/docs/Documentation/03a-stoplight-flavored-markdown.md) [CommonMark](https://commonmark.org/) format which in turn is a less ambiguous formal definition of [Markdown](https://www.markdownguide.org/).\nThese API definitions can be used to generate stub code for either server or client side. Currently, we only do this with the `clinic` service (see below for special note on that).\n\n## Workflow\n\nWe have an account in [Stoplight](https://tidepool.stoplight.io) for publishing the documentation and API specifications. The goal is for that site to soon replace the current [developer portal](https://developer.tidepool.org). It *is* possible to edit the documentation files directly online in Stoplight - however we are *not* using that capability, for several reasons:\n\n1. Doing so requires using one of a limited number of seats (5).\n2. It does not fit well into our normal review/approval workflow.\n3. It requires integration with GitHub with [broad scopes including access to private repositories](https://support.stoplight.io/s/article/Github-OAuth-Permissions-Overview).\n4. It does not enable us to run pre-merge checks, in particular to validate changes that could break generated server stub code such as the [`clinic`](https://github.com/tidepool-org/clinic) service. See the `check` and `generate` steps in the [Makefile](./Makefile).\n5. It does not enable us to run pre-processing steps necessary to consolidate multiple API specification files into a single OpenAPI v3 specification to make the published API view more coherent. See the `prepare` steps in the [Makefile](./Makefile).\n6. We automatically publish two sets of API specifications from the same source files:\n   1. *public* documentation that only describes APIs useful to client application developers.\n   2. *private/full* documentation that describes all APIs, even ones that are only accessible to Tidepool team internal use.\n\nThe preferred workflow is to edit these files offline, then commit them to GitHub which automatically pushes updates into Stoplight, including work branches though they are not visible to people outside of Tidepool. Here are the workflow details:\n\n1. Clone this repository and install the validation \u0026 publishing tools. You only need to to this once.\n\n    ```shell\n    git clone https://github.com/tidepool-org/TidepoolApi.git\n    cd TidepoolApi\n    make install_tools\n    ```\n\n2. Create a *work branch* for your edits:\n\n    ```shell\n    git checkout master\n    git pull\n    git checkout master -b {branch}\n    ```\n\n3. Edit and preview the files offline using any of the [tools](#editing-tools) listed below.\n4. Validate your changes locally:\n\n    ```shell\n    make check\n    make prepare\n    ```\n\n5. Commit your changes to the work branch and push to GitHub. This will automatically kick off a [GitHub Action](.github/workflows/) that checks \u0026 publishes the new (draft) documentation into a branch in Stoplight.\n\n    ```shell\n    git add {file(s)}\n    git commit -m \"{description}\"\n    git checkout master\n    git pull\n    git checkout {branch}\n    git merge --no-ff master\n    git push -u origin HEAD\n    ```\n\n6. Post a pull request (PR) to review the changes\n7. Once the PR is approved, merge to master which will again automatically update the master branch in the Stoplight site.\n\nIt is also possible to publish your work branch to Stoplight from your local folder. You will need the API tokens for Stoplight stored in \n\n### Adding New Specification Files\n\nIf you add a brand new top-level OpenAPI 3.0 specification file, it needs to be added to the [`templates/openapi-merge.jsonnet`](./templates/openapi-merge.jsonnet) template file so that it gets included in the combined specification file that is published in Stoplight.\n\n## Publishing Tokens\n\nTo publish documentation and API specifications locally, you will need the corresponding API token from Stoplight. Those API tokens are not directly found in the Stoplight project settings UI, but they are documented [here](https://docs.stoplight.io/docs/platform/f76c84240244f-publish-with-the-stoplight-cli) or if that link no longer works, [Google for it](https://www.google.com/search?q=Publish+with+Stoplight+CLI).\n\nThe tokens are configured as secrets for the GitHub Actions and can be found here:\n\n* Token for [Public API](https://tidepool.stoplight.io/settings/tidepool-api/automation)\n* Token for [Full API](https://tidepool.stoplight.io/settings/tidepool-full-api/automation)\n\n## Landing Page\n\nThe contents in Tidepool's organization [home page](https://tidepool.stoplight.io/) in Stoplight comes from a file in this repository. To update it:\n\n1. Edit the [landing.md](./landing.md) Markdown file.\n2. Commit the changes \u0026 push to GitHub, for posterity.\n3. Copy \u0026 paste the file's Markdown contents into the [Settings](https://tidepool.stoplight.io/admin/settings) page. This requires admin permissions in Stoplight.\n\n![Updating Landing Page](./assets/images/updating-landing-page.png)\n\n## Editing Tools\n\n1. Free [Stoplight Studio](https://stoplight.io/studio/). This is the recommended tool since it is the closest rendering to the publishing site.\n2. Free Microsoft [Visual Studio Code](https://code.visualstudio.com/), with plug-ins for validating and rendering OpenAPI v3 specifications and Markdown documentation.\n3. Many other IDEs offer similar plug-ins.\n\n## Other Tools\n\nThe [Makefile](./Makefile) makes use of several CLI tools to check, prepare, and publish the documentation and specifications.\nYou can install the tools by executing the following command:\n\n```shell\nmake install_tools\n```\n\nYou can check if you have all the tools installed by executing the following command:\n\n```shell\nmake check_tools\n```\n\n| Tool | Description |\n|------|-------------|\n| [markdownlint](https://www.npmjs.com/package/markdownlint) | Validates Markdown files. |\n| [markdown-link-check](https://www.npmjs.com/package/markdown-link-check) | Validates hyperlinks in Markdown files. |\n| [spectral](https://www.npmjs.com/package/@stoplight/spectral) | Validates OpenAPI 3.0 specification files. |\n| [swagger-cli](https://www.npmjs.com/package/swagger-cli) | Validates OpenAPI 3.0 specification files. Also bundles multiple OAS3 files into a single file, that is required by some downstream use-cases. |\n| [redocly](https://github.com/Redocly/redocly-cli) | Validates OpenAPI 3.0 specification files. Also bundles multiple OAS3 files into a single file, that is required by some downstream use-cases. |\n| [jsonnet](https://jsonnet.org/) | Data templating tool. Used here to generate the configuration file for `openapi-merge-cli`. |\n| [openapi-merge-cli](https://www.npmjs.com/package/openapi-merge-cli) | Merges OpenAPI 3.0 specification files into single file. |\n| [stoplight](https://www.npmjs.com/package/@stoplight/cli) | Publishes OpenAPI 3.0 specifications and documentation in Markdown format to Stoplight's web site. |\n| [oapi-codegen](https://github.com/deepmap/oapi-codegen) | Generates server and client stub code from OpenAPI 3.0 specifications. Used currently to generate the [`clinic`](https://github.com/tidepool-org/clinic) service code. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidepool-org%2Ftidepoolapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftidepool-org%2Ftidepoolapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftidepool-org%2Ftidepoolapi/lists"}