github.com/phrase/openapi@v0.0.0-20240514140800-49e8a106740e/README.md (about) 1 # OpenAPI specification for Phrase 2 3 ## Commands 4 5 * `npm install` installs the dependencies 6 * `npm start` builds API clients 7 * `npm run docs` generates API documentation in HTML 8 * `npm run watch` starts a local server which you can reach at http://localhost:8080 9 * `npm run lint` lints your changes 10 11 ## Contribution 12 13 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. 14 15 These changelogs and version bumps are generated as a separate pull requests (one for each client library) and currently need to be merged manually. 16 17 ### Example 18 19 You added an endpoint in Phrase Strings. In this project you do the following: 20 21 1. Add newly added schema (if any) to `/schemas/` directory 22 2. Add new endpoints to `/paths/` directory and reference it in `paths.yaml` 23 3. `npm start` to re-build the clients 24 4. `npm run docs` to generate the documentation (and verify it in action using `npm run watch`) 25 5. Open a PR with an informative title (e.g. `feat(api): Add an API endpoint for cat pics`) 26 27 ## Workflow 28 29 The following repositories are generated upon pushing to this one: 30 31 https://github.com/phrase/phrase-go 32 33 https://github.com/phrase/phrase-java 34 35 https://github.com/phrase/phrase-js 36 37 https://github.com/phrase/phrase-php 38 39 https://github.com/phrase/phrase-python 40 41 https://github.com/phrase/phrase-ruby 42 43 https://github.com/phrase/phrase-cli 44 45 ### Deployment diagram 46 47 ![Deployment diagram](docs/openapi%20workflow.svg) 48 49 ## Specification 50 51 [http://spec.openapis.org/oas/v3.0.3](http://spec.openapis.org/oas/v3.0.3) 52 53 [https://swagger.io/specification/#specification](https://swagger.io/specification/#specification) 54 55 [https://swagger.io/docs/specification/about/](https://swagger.io/docs/specification/about/) 56 57 ### Defining parameters 58 59 `POST`/`PUT` requests should define parameters within `requestBody` section, like the following: 60 61 ```yaml 62 requestBody: 63 required: true 64 content: 65 application/json: 66 schema: 67 type: object 68 title: key/create/parameters 69 properties: 70 branch: 71 description: specify the branch to use 72 type: string 73 example: my-feature-branch 74 name: 75 description: Key name 76 type: string 77 example: home.index.headline 78 ``` 79 80 `parameters` section should contain only those parameters which are part of the URL (typically `project_id` and/or `account_id`) 81 82 ## Get help / support 83 84 Please contact [support@phrase.com](mailto:support@phrase.com?subject=[GitHub]%20openapi) and we can take more direct action toward finding a solution.