Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phrase/openapi
OpenAPI specification for Phrase Strings REST API
https://github.com/phrase/openapi
documentation openapi openapi-specification swagger
Last synced: 6 days ago
JSON representation
OpenAPI specification for Phrase Strings REST API
- Host: GitHub
- URL: https://github.com/phrase/openapi
- Owner: phrase
- License: mit
- Created: 2020-04-20T12:10:31.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-12T19:50:30.000Z (7 months ago)
- Last Synced: 2024-04-13T08:32:14.261Z (7 months ago)
- Topics: documentation, openapi, openapi-specification, swagger
- Language: Mustache
- Homepage: https://developers.phrase.com/api/
- Size: 3.97 MB
- Stars: 10
- Watchers: 19
- Forks: 9
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# OpenAPI specification for Phrase
## Commands
* `npm install` installs the dependencies
* `npm start` builds API clients
* `npm run docs` generates API documentation in HTML
* `npm run watch` starts a local server which you can reach at http://localhost:8080
* `npm run lint` lints your changes
## Contribution
This project relies on [conventional commits](https://www.conventionalcommits.org) used by [release-please](https://github.com/googleapis/release-please) to generate proper changelogs and increment versions of the generated client libraries affected by the PR. Please use [appropriate prefixes](https://kapeli.com/cheat_sheets/Conventional_Commits.docset/Contents/Resources/Documents/index) when giving titles to your PRs as they decide whether there will be a version bump and changelog entry.
These changelogs and version bumps are generated as a separate pull requests (one for each client library) and currently need to be merged manually.
### Example
You added an endpoint in Phrase Strings. In this project you do the following:
1. Add newly added schema (if any) to `/schemas/` directory
2. Add new endpoints to `/paths/` directory and reference it in `paths.yaml`
3. `npm start` to re-build the clients
4. `npm run docs` to generate the documentation (and verify it in action using `npm run watch`)
5. Open a PR with an informative title (e.g. `feat(api): Add an API endpoint for cat pics`)
## Workflow
The following repositories are generated upon pushing to this one:
https://github.com/phrase/phrase-go
https://github.com/phrase/phrase-java
https://github.com/phrase/phrase-js
https://github.com/phrase/phrase-php
https://github.com/phrase/phrase-python
https://github.com/phrase/phrase-ruby
https://github.com/phrase/phrase-cli
### Deployment diagram
## Specification
[http://spec.openapis.org/oas/v3.0.3](http://spec.openapis.org/oas/v3.0.3)
[https://swagger.io/specification/#specification](https://swagger.io/specification/#specification)
[https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/)
### Defining parameters
`POST`/`PUT` requests should define parameters within `requestBody` section, like the following:
```yaml
requestBody:
required: true
content:
application/json:
schema:
type: object
title: key/create/parameters
properties:
branch:
description: specify the branch to use
type: string
example: my-feature-branch
name:
description: Key name
type: string
example: home.index.headline
```
`parameters` section should contain only those parameters which are part of the URL (typically `project_id` and/or `account_id`)
## Get help / support
Please contact [[email protected]](mailto:[email protected]?subject=[GitHub]%20openapi) and we can take more direct action toward finding a solution.