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.