Never Propel Marmalade

    @credify/api-docs
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    Credify API doc OpenAPI Definition

    TypeScript types

    This repository automatically generates TypeScript interfaces based on openapi.yaml. Please install the latest version with npm or yarn.

    Install

    yarn add -D @credify/api-docs
    
    npm install --dev @credify/api-docs

    Usage

    components contains all the definitions.

    import { components } from "@credify/api-docs";
    
    const response: components["AccessTokenResponse"] = {
      ...
    }

    Deployment

    Once you finish your changes on this repository, please make a tag from master branch. GitHub Action will be kicked off to deploy the latest types package.


    Working on your OpenAPI Definition

    Install

    1. Install Node JS.
    2. Clone this repo and run npm install in the repo root.

    Usage

    npm start

    Starts the reference docs preview server.

    npm run build

    Bundles the definition to the dist folder.

    npm test

    Validates the definition.

    Contribution Guide

    Below is a sample contribution guide. The tools in the repository don't restrict you to any specific structure. Adjust the contribution guide to match your own structure. However, if you don't have a structure in mind, this is a good place to start.

    Update this contribution guide if you adjust the file/folder organization.

    The .redocly.yaml controls settings for various tools including the lint tool and the reference docs engine. Open it to find examples and read the docs for more information.

    Schemas

    Adding Schemas

    1. Navigate to the docs/components/schemas folder.
    2. Add a file named as you wish to name the schema.
    3. Define the schema.
    4. Refer to the schema using the $ref (see example below).
    Example Schema

    This is a very simple schema example:

    type: string
    description: The resource ID. Defaults to UUID v4
    maxLength: 50
    example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21

    This is a more complex schema example:

    type: object
    properties:
      id:
        description: The customer identifier string
        readOnly: true
        allOf:
          - $ref: ./ResourceId.yaml
      websiteId:
        description: The website's ID
        allOf:
          - $ref: ./ResourceId.yaml
      paymentToken:
        type: string
        writeOnly: true
        description: |
          A write-only payment token; if supplied, it will be converted into a
          payment instrument and be set as the `defaultPaymentInstrument`. The
          value of this property will override the `defaultPaymentInstrument`
          in the case that both are supplied. The token may only be used once
          before it is expired.
      defaultPaymentInstrument:
        $ref: ./PaymentInstrument.yaml
      createdTime:
        description: The customer created time
        allOf:
          - $ref: ./ServerTimestamp.yaml
      updatedTime:
        description: The customer updated time
        allOf:
          - $ref: ./ServerTimestamp.yaml
      tags:
        description: A list of customer's tags
        readOnly: true
        type: array
        items:
          $ref: ./Tags/Tag.yaml
      revision:
        description: >
          The number of times the customer data has been modified.
    
          The revision is useful when analyzing webhook data to determine if the
          change takes precedence over the current representation.
        type: integer
        readOnly: true
      _links:
        type: array
        description: The links related to resource
        readOnly: true
        minItems: 3
        items:
          anyOf:
            - $ref: ./Links/SelfLink.yaml
            - $ref: ./Links/NotesLink.yaml
            - $ref: ./Links/DefaultPaymentInstrumentLink.yaml
            - $ref: ./Links/LeadSourceLink.yaml
            - $ref: ./Links/WebsiteLink.yaml
      _embedded:
        type: array
        description: >-
          Any embedded objects available that are requested by the `expand`
          querystring parameter.
        readOnly: true
        minItems: 1
        items:
          anyOf:
            - $ref: ./Embeds/LeadSourceEmbed.yaml
    
    Using the $ref

    Notice in the complex example above the schema definition itself has $ref links to other schemas defined.

    Here is a small excerpt with an example:

    defaultPaymentInstrument:
      $ref: ./PaymentInstrument.yaml

    The value of the $ref is the path to the other schema definition.

    You may use $refs to compose schema from other existing schema to avoid duplication.

    You will use $refs to reference schema from your path definitions.

    Editing Schemas

    1. Navigate to the docs/components/schemas folder.
    2. Open the file you wish to edit.
    3. Edit.

    Paths

    Adding a Path

    1. Navigate to the docs/paths folder.
    2. Add a new YAML file named like your URL endpoint except replacing / with @ and putting path parameters into curly braces like {example}.
    3. Add the path and a ref to it inside of your openapi.yaml file inside of the docs folder.

    Example addition to the openapi.yaml file:

    '/customers/{id}':
      $ref: './paths/customers@{id}.yaml'

    Here is an example of a YAML file named customers@{id}.yaml in the paths folder:

    get:
      tags:
        - Customers
      summary: Retrieve a list of customers
      operationId: GetCustomerCollection
      description: |
        You can have a markdown description here.
      parameters:
        - $ref: ../components/parameters/collectionLimit.yaml
        - $ref: ../components/parameters/collectionOffset.yaml
        - $ref: ../components/parameters/collectionFilter.yaml
        - $ref: ../components/parameters/collectionQuery.yaml
        - $ref: ../components/parameters/collectionExpand.yaml
        - $ref: ../components/parameters/collectionFields.yaml
      responses:
        '200':
          description: A list of Customers was retrieved successfully
          headers:
            Rate-Limit-Limit:
              $ref: ../components/headers/Rate-Limit-Limit.yaml
            Rate-Limit-Remaining:
              $ref: ../components/headers/Rate-Limit-Remaining.yaml
            Rate-Limit-Reset:
              $ref: ../components/headers/Rate-Limit-Reset.yaml
            Pagination-Total:
              $ref: ../components/headers/Pagination-Total.yaml
            Pagination-Limit:
              $ref: ../components/headers/Pagination-Limit.yaml
            Pagination-Offset:
              $ref: ../components/headers/Pagination-Offset.yaml
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: ../components/schemas/Customer.yaml
            text/csv:
              schema:
                type: array
                items:
                  $ref: ../components/schemas/Customer.yaml
        '401':
          $ref: ../components/responses/AccessForbidden.yaml
      x-code-samples:
        - lang: PHP
          source:
            $ref: ../code_samples/PHP/customers/get.php
    post:
      tags:
        - Customers
      summary: Create a customer (without an ID)
      operationId: PostCustomer
      description: Another markdown description here.
      requestBody:
        $ref: ../components/requestBodies/Customer.yaml
      responses:
        '201':
          $ref: ../components/responses/Customer.yaml
        '401':
          $ref: ../components/responses/AccessForbidden.yaml
        '409':
          $ref: ../components/responses/Conflict.yaml
        '422':
          $ref: ../components/responses/InvalidDataError.yaml
      x-code-samples:
        - lang: PHP
          source:
            $ref: ../code_samples/PHP/customers/post.php

    You'll see extensive usage of $refs in this example to different types of components including schemas.

    You'll also notice $refs to code samples.

    Code samples

    1. Navigate to the docs/code_samples folder.
    2. Navigate to the <language> (e.g. PHP) sub-folder.
    3. Navigate to the path folder, and add ref to the code sample.

    You can add languages by adding new folders at the appropriate path level.

    More details inside the code_samples folder README.

    Keywords

    none

    Install

    npm i @credify/api-docs

    DownloadsWeekly Downloads

    66

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    331 kB

    Total Files

    565

    Last publish

    Collaborators

    • ngo275
    • credify-pte-ltd