redocly.yaml

apis:
  core@public:
    root: openapi/openapi.yaml
    output: docs/dev-docs/api/index.yaml
    metadata:
      description: The most common APIs used to automate common workflows.
    decorators:
      filter-in:
        property: x-products
        value:
          - Core
      plugin/change-title:
        title: Core APIs
  core@latest:
    root: openapi/openapi.yaml
    output: catalog/core.yaml
    metadata:
      description: The most common APIs used to automate common workflows.
    decorators:
      filter-in:
        property: x-products
        value:
          - Core
      plugin/change-title:
        title: Core APIs
  all@latest:
    root: openapi/openapi.yaml
    output: catalog/all.yaml
    metadata:
      description: All Rebilly APIs.
    decorators:
      plugin/remove-tag-groups: on
      plugin/change-title:
        title: All APIs
  all@3.0:
    root: openapi/openapi.yaml
    output: catalog/all-3.0.yaml
    metadata:
      description: All Rebilly APIs.
    decorators:
      plugin/remove-tag-groups: on
      plugin/change-title:
        title: All APIs
      plugin/backport-to-30: on
  storefront@latest:
    root: openapi/openapi.yaml
    output: catalog/storefront.yaml
    metadata:
      description: APIs intended to be used directly from an untrusted browser.
    decorators:
      filter-in:
        property: x-products
        value:
          - Storefront
      plugin/change-title:
        title: Storefront APIs
      plugin/remove-tag-groups: on
      plugin/remove-unused-tags: on
  reports@latest:
    root: openapi/openapi.yaml
    output: catalog/reports.yaml
    metadata:
      description: APIs for reporting purposes.
    decorators:
      filter-in:
        property: x-products
        value:
          - Reports
      plugin/change-title:
        title: Reports APIs
      plugin/remove-tag-groups: on
      plugin/remove-unused-tags: on
  combined@latest:
    root: openapi/openapi.yaml
    output: catalog/combined.yaml
    metadata:
      description: Combined APIs for who knows what. Maybe we can remove this since we have "All"?
    decorators:
      filter-in:
        property: x-products
        value:
          - Combined
      plugin/change-title:
        title: Combined APIs
      plugin/remove-tag-groups: on
      plugin/remove-unused-tags: on
  users@latest:
    root: openapi/openapi.yaml
    output: catalog/users.yaml
    metadata:
      description: Users APIs for who knows what. Maybe we can remove this since we have "All"?
    decorators:
      filter-in:
        property: x-products
        value:
          - Users
      plugin/change-title:
        title: Users APIs
      plugin/remove-tag-groups: on
      plugin/remove-unused-tags: on
extends:
  - recommended
plugins:
  - ./plugins/custom-rules.js
  - ./plugins/decorators.js
  - ./plugins/products-bundler/bundler.js
rules:
  no-ambiguous-paths: error
  no-unused-components: error
  operation-2xx-response: error
  operation-operationId: error
  operation-singular-tag: error
  operation-tag-defined: error
  operation-4xx-response: off
  paths-kebab-case: error

  tags-alphabetical:
    severity: error
    ignoreCase: true
  request-mime-type:
    severity: error
    allowedValues:
      - application/json
  response-mime-type:
    severity: error
    allowedValues:
      - application/json
      - application/pdf
      - application/zip
      - image/jpg
      - image/png
      - image/gif
      - text/csv
  # Opened a ticket:
  # response-contains-property:
  #   severity: error
  #   names:
      # '2XX':
      #   - createdTime
      #   - updatedTime
      #   - id
      #   - _links
      # '4XX':
      #   - type
      #   - status
      #   - title
  rule/response-contains-property:
    severity: off
    subject:
      type: SchemaProperties
    where:
      - subject:
          type: Response
          filterInParentKeys:
            - '200'
            - '201'
            - '202'
        assertions:
          defined: true
      - subject:
          type: Schema
          property: type
        assertions:
          const: object
    assertions:
      required:
        - id
        - _links
  rule/response-error-contains-property:
    severity: off
    subject:
      type: SchemaProperties
    where:
      - subject:
          type: Response
          filterInParentKeys:
            - '422'
            - '400'
            - '409'
        assertions:
          defined: true
      - subject:
          type: Schema
          property: type
        assertions:
          const: object
    assertions:
      required:
        - type
        - status
        - title

  path-segment-plural:
    severity: error
    ignoreLastPathSegment: true
    exceptions:
      - storefront
      - experimental
      - tracking
      - profile
      - verification
      - reset-password
      - account
      - events-triggered
      - status
      - send-through-attribution
      - permissions-emulation
      - logout
      - onboarding
      - timeline
      - edd-timeline
      - forgot-password
      - history
      - search
      - ready-to-pay
      - aml
      - api
      - upcoming-invoice
  custom-rules/no-unused-tags: error
  custom-rules/sibling-ref: error
  response-contains-header:
    severity: error
    names:
      '201':
        - Location
      '303':
        - Location
  no-invalid-schema-examples: error
  no-invalid-media-type-examples: error
  no-invalid-parameter-examples: error
  no-server-example.com: error
  no-http-verbs-in-paths:
    severity: error
    splitIntoWords: true
  boolean-parameter-prefixes: error
  parameter-description: error
  ## custom rules
  ### Examples
  rule/params-must-include-examples:
    severity: off
    subject:
      type: Parameter
    assertions:
      requireAny:
        - example
        - examples
      mutuallyExclusive:
        - example
        - examples

  rule/headers-include-example:
    subject:
      type: Header
      property: example
    assertions:
      defined: true
      nonEmpty: true

  rule/path-must-be-ref-file:
    subject:
      type: PathItem
    where:
      - subject:
          type: Paths
        assertions:
          defined: true
    assertions:
      ref: /^(.\/paths|paths)\/[a-z{].*yaml$/

  rule/x-sdk-operation-name:
    where:
      - subject:
          type: Paths
        assertions:
          defined: true
    subject:
      type: Operation
      property: x-sdk-operation-name
    assertions:
      casing: camelCase
      defined: true

  rule/operation-id-delete:
    where:
      - subject:
          type: Operation
          filterInParentKeys:
            - delete
        assertions:
          defined: true
    subject:
      type: Operation
      property: operationId
    assertions:
      pattern: /Delete/
      casing: PascalCase

  rule/operation-id-get:
    where:
      - subject:
          type: Operation
          filterInParentKeys:
            - get
        assertions:
          defined: true
    subject:
      type: Operation
      property: operationId
    assertions:
      pattern: /Get/
      casing: PascalCase

  rule/operation-id-patch:
    where:
      - subject:
          type: Operation
          filterInParentKeys:
            - patch
        assertions:
          defined: true
    subject:
      type: Operation
      property: operationId
    assertions:
      pattern: /Patch/

  rule/operation-id-post:
    where:
      - subject:
          type: Paths
        assertions:
          defined: true
      - subject:
          type: Operation
          filterInParentKeys:
            - post
        assertions:
          defined: true
    subject:
      type: Operation
      property: operationId
    assertions:
      pattern: /Post/
      casing: PascalCase

  rule/operation-id-put:
    where:
      - subject:
          type: Operation
          filterInParentKeys:
            - put
        assertions:
          defined: true
    subject:
      type: Operation
      property: operationId
    assertions:
      pattern: /Put/
      casing: PascalCase

  rule/operation-summary:
    subject:
      type: Operation
      property: summary
    where:
      - subject:
          type: Paths
        assertions:
          defined: true
    assertions:
      defined: true
      minLength: 10
      maxLength: 50
      pattern: /^(Retrieve|Create|Delete|Upsert|Preview|Send|Update|Register|Destroy|Trigger|Start|Stop|Skip|Set|Check|Enable|Disable|Close|Request|Resend|Verify|List|Patch|Activate|Refund|Query|Validate|Tag|Untag|Issue|Reactivate|Cancel|Pause|Change|Void|Search|Get|Modify|Finish|Schedule|Read|Reset|Make|Deactivate|Perform|Review|Reject|Accept|Apply|Partially|Re|Abandon|Download|Merge|Specify|Redeem|Exchange|Log|Sync).*[^\.]$/

  ### Description rules
  rule/tag-description:
    subject:
      type: Tag
      property: description
    assertions:
      defined: true
  rule/description-capitalization:
    subject:
      type: any
      property: description
    assertions:
      pattern: /^([A-Z]|#+ [A-Z]|dLocal|ecoPayz|eMerchantPay|ePay|eZeeWallet|ezyEFT|iCanPay|iCheque|iDebit|loonie|vegaaH|gate2way)/
  rule/description-punctuation:
    subject:
      type: any
      property: description
    assertions:
      pattern: /(\.\n?|server)$/
  rule/no-anthropomorphic-possessives:
    subject:
      type: any
      property: description
    assertions:
      notPattern: /(Rebilly's|subscription's|invoice's|item's|order's|product's|transaction's|document's|payment's|payout's|card's|instrument's)/i

  rule/no-description-start-with-the-a-an:
    subject:
      type: any
      property: description
    assertions:
      notPattern: /^(The\s|A\s|An\s)/
  rule/no-past-future:
    subject:
      type: any
      property: description
    assertions:
      notPattern: /(was\s|were\s|will\s)/

  rule/info-description:
    subject:
      type: Info
      property: description
    assertions:
      defined: true
      minLength: 30

  rule/schema-properties-both-created-time-and-updated-time:
    subject:
      type: SchemaProperties
    assertions:
      mutuallyRequired:
        - createdTime
        - updatedTime

  rule/schema-properties-camelCase:
    where:
      - subject:
          type: SchemaProperties
          property: credentials
        assertions:
          defined: false
      - subject:
          type: SchemaProperties
        assertions:
          notPattern: ^(_embedded|_links|q|25th|50th|75th|3ds)$
    subject:
      type: SchemaProperties
    assertions:
      casing: camelCase

  rule/put-200-and-201:
    subject:
      type: Responses
    where:
      - subject:
          type: Operation
          filterInParentKeys:
            - put
        assertions:
          defined: true
    message: Must mutually define 200 and 201 responses for PUT requests.
    severity: warn
    assertions:
      mutuallyRequired:
        - '200'
        - '201'

  rule/no-x-code-samples:
    subject:
      type: Operation
    assertions:
      disallowed:
        - x-code-samples

  rule/no-x-internal:
    subject:
      type: Operation
    message: This is in a public repository. Do not include internal APIs.
    assertions:
      disallowed:
        - x-internal

  rule/embedded-is-object:
    severity: error
    subject:
      type: Schema
      property: type
      filterInParentKeys:
        - _embedded
    assertions:
      const: object

      # Need to account for arrays, etc...
  # rule/mediatype-schema-ref-pattern:
  #   subject: MediaType
  #   property: schema
  #   message: Ref needs to point to components directory.
  #   ref: /^(\.\.\/)?(components|schemas)\/.*\.yaml$/

decorators:
  products-bundler/bundle: error
  plugin/remove-php-sample-prefix: on
theme:
  openapi:
    pagination: item
    theme:
      logo:
        gutter: 20px 30px 14px 30px
      colors:
        primary:
          main: '#0044D4'
        text:
          primary: '#0D2B3E'
      typography:
        headings:
          fontFamily: Roboto
        fontFamily: 'Roboto, Verdana, Geneva, sans-serif'
        fontSize: 14px
        code:
          fontFamily: '"Courier New",monospace'
        rightPanelHeading:
          color: white
      rightPanel:
        backgroundColor: '#505A6F'
      codeBlock:
        backgroundColor: '#0D2B3E'
      links:
        color: '#6CC496'
    htmlTemplate: ./web/index.html
    generateCodeSamples:
      languages:
        - lang: curl
        - lang: Node.js
        - lang: Ruby
        - lang: C#
        - lang: Go
        - lang: Python
        - lang: Java
    schemaExpansionLevel: '2'
    maxDisplayedEnumValues: 10
    hideTryItPanel: false
    expandResponses: '200,201'
    requiredPropsFirst: true
  catalog:
    rebilly-catalog:
      title: Rebilly API catalog
      description: Discover how our APIs can support your business.
      slug: /catalog/
      items:
        - directory: ./catalog
          flatten: true
          includeByMetadata:
            type: [openapi]
  navbar:
    items:
      - page: /catalog/
        label: Catalog
      - page: /contributing/
        label: Contributing
  logo:
    altText: Rebilly API catalog
    image: ./web/rb_apiLogo.svg
ignore:
  - '.github' # works
  # - 'openapi'
  - 'plugins'
  - 'web'
  # - 'CONTRIBUTING.md'
  # - 'README.md'