query-api-config.yml

# This config will not run "as-is" and will need to be modified. You can see a minimal working
# config in /examples/config.yml

spectaql:
  # Optional path to an image to use as the logo in the top-left of the output
  logoFile: ../../front/src/assets/images/Boxtribute Main Logo-03@2x.png
  # Optional path to an image to use as a favicon for the site when it's not embedded
  # faviconFile: path/to/favicon.png

introspection:
  ##############################################
  # These options specify where/how to get the information requried to generate your
  # documentation.
  #
  # Each of these have corresponding CLI options where they can be expressed instead of here.
  # The CLI options will take precedence over what is in your config file
  #
  # 1 and only 1 of the following options must be provided:
  #

  # URL of the GraphQL endpoint to hit if you want to generate the documentation based on live Introspection Query results
  # NOTE: If not using introspection.url OR servers[], you need to provide x-url
  # to satisfy the URL Swagger requirement.
  # url: https://yoursite.com/graphql

  # If using the "url" option above, any headers (such as Authorization) can be added here. This
  # can also be added via the CLI options
  # headers:
  #   Authorization: Bearer s3cretT0k2n

  # File containing a GraphQL Schema Definition written in SDL.
  # Can also pass an array of paths (or glob supported by @graphql-tools/load-files)
  # like so:
  # schemaFile:
  #   - path/to/schema/part1.gql
  #   - path/to/schema/part2.gql
  schemaFile:
    - ../../back/boxtribute_server/graph_ql/definitions/protected/types.graphql
    - ../../back/boxtribute_server/graph_ql/definitions/protected/queries.graphql
    - ../../back/boxtribute_server/graph_ql/definitions/basic/*.graphql
    - ../../back/boxtribute_server/graph_ql/definitions/public/types.graphql

  # File containing Introspection Query response in JS module export, or JSON format
  # introspectionFile: path/to/introspection.js[on]

  #
  #
  ##############################################

  ##############################################
  # These options are for random display or augmentation related things that didn't
  # really fit anywhere else.
  #

  # Whether you would like to strip any trailing commas from the descriptions to keep
  # things fresh and clean.
  #
  # Default: false
  removeTrailingPeriodFromDescriptions: false

  #
  #
  ##############################################

  ##############################################
  # These options specify how, where and if any "metadata" information is to be added to your Introspection
  # Query results IF it is not already present. If you are not dealing with metadata, or you have already
  # baked it into your Introspection Query results somehow (on the server-side, for example) then you
  # can ignore these options completely.
  #

  # File that contains your metadata data in JS module export, or JSON format
  metadataFile: metadata.json

  # The path to a key from which to read the documentation-related metadata at each level of your metadata file.
  # Defaults to 'documentation', but in case you use a different name, or have a complex/nested metadata structure, you can
  # specify it here.
  #
  # Default: documentation
  # metadatasReadPath: documentation

  # The metadata that was just read from the above key path will be woven into your Introspection Query results.
  # This option specifies the key path where that data will be written at each level.
  #
  #   ***
  #   In order to ensure that the metadata you've written can be found later on down the line, this value
  #   should be set the same as the "metadatasPath" option below
  #   ***
  #
  # Defaults to 'documentation', but in case you have a complex/nested metadata structure, you can
  # specify it here.
  #
  # Default: documentation
  # metadatasWritePath: documentation

  #
  #
  ##############################################

  ##############################################
  # These options specify how, where and if any "metadata" information is to be found, or
  # used/ignored when processing your documentation.
  #

  # The key path in your Introspection Query results where metadata supported by this library can
  # be found.
  # Defaults to 'documentation', but in case you have a complex/nested metadata structure, you can
  # specify it here.
  #
  # Default: documentation
  # metadatasPath: documentation

  # Whether or not to look for and use metadata in your data. If turned off, metadata will be ignored
  # even if it's there
  #
  # Default: true
  metadatas: false

  #
  #
  ##############################################

  # This allows you to specify a custom path to a JS moddule to handle the generation of
  # example values for your schema. The default is "./customizations/examples" which starts
  # out doing nothing
  #
  # Default: ./customizations/examples
  # dynamicExamplesProcessingModule: path/to/examples.js

  ##############################################
  # These options specify what the default behavior should be
  # (regarding documented vs non-documented) in the absence of
  # metadata directives on a given item

  # Whether to document any Queries at all, in the absence of a metadata directive
  # Default: true
  queriesDocumentedDefault: true
  # Whether to document an individual Query, in the absence of a metadata directive
  # Default: true
  queryDocumentedDefault: true
  # Whether to document a Query Argument, in the absence of a metadata directive
  # Default: true
  queryArgDocumentedDefault: true
  # Hide any Queries with undocumented return types so as not to reference something
  # that seemingly does not exist.
  # Default: true
  hideQueriesWithUndocumentedReturnType: true

  # Whether to document any Mutations at all, in the absence of a metadata directive
  # Default: true
  mutationsDocumentedDefault: true
  # Whether to document an individual Mutation, in the absence of a metadata directive
  # Default: true
  mutationDocumentedDefault: true
  # Whether to document a Mutation Argument, in the absence of a metadata directive
  # Default: true
  mutationArgDocumentedDefault: true
  # Hide any Mutations with undocumented return types so as not to reference something
  # that seemingly does not exist.
  # Default: true
  hideMutationsWithUndocumentedReturnType: true

  # Whether to document any Types at all
  # Default: true
  objectsDocumentedDefault: true
  # Whether to document an individual Type, in the absence of a metadata directive
  # Default: true
  objectDocumentedDefault: true
  # Whether to document an individual Field, in the absence of a metadata directive
  # Default: true
  fieldDocumentedDefault: true
  # Whether to document an individual Argument, in the absence of a metadata directive
  # Default: true
  argDocumentedDefault: true
  # Hide any fields with undocumented return types so as not to reference something
  # that seemingly does not exist.
  # Default: true
  hideFieldsOfUndocumentedType: true

  #
  #
  ##############################################

servers:
  # NOTE: If not using introspection.url OR servers[], you need to provide x-url
  # to satisfy the URL Swagger requirement.

  # same format as for OpenAPI Specification https://swagger.io/specification/#server-object

  - url: https://api.boxtribute.org
    description: Query API
    # Indicates to use this server's URL as the typical GraphQL request base in the documentation
    # If no server entries have this indicator, the first server's URL will be used.
    # If no server entries are defined at all, the Introspection URL will be used.
    production: true

info:
  # Tries to adhere to OpenAPI Specification https://swagger.io/specification/#info-object
  # Will be used to populate the Welcome section of the output

  ##############################################
  # Introduction area flags
  #

  # Set to true to do no Introduction area rendering at all. Supersedes the below options
  # Default: false
  x-hideIntroduction: false
  # Set to true to not render a friendly Welcome section based on the description in this area
  # Default: false
  x-hideWelcome: false
  # Set to true to not render your intro items
  # Default: false
  x-hideIntroItems: false

  # Set to true to not render the deprecated label
  # Default: false
  x-hideIsDeprecated: false
  # Set to true to not render the deprecation reason
  # Default: false
  x-hideDeprecationReason: false

  #
  ##############################################

  description: |
    These pages contain the documentation for the boxtribute GraphQL API (queries only). Have fun exploring!

    You can interact with the API in either of the following ways:
    - Open the endpoint address in your browser. This launches the GraphQL explorer
    - Send POST requests to the endpoint from a script or the command line, passing your GraphQL query in the `query` field of the request JSON
  # Don't change the version number manually. It's substituted at deploy time in CircleCI
  version: 0.0.1
  title: Welcome!
  # This is non-standard and optional. If omitted, will use "title". Also only relevant
  # when building non-embedded.
  x-htmlTitle: boxtribute GraphQL API documentation
  contact:
    name: boxtribute Support
    email: help@boxtribute.org
    url: https://www.boxtribute.org
  license:
    name: Apache 2.0
    url: "https://github.com/boxwise/boxtribute/blob/master/LICENSE.md"

  # A non-standard array of items to display in your Introduction Area
  x-introItems:
    # Can be a Title (for the Nav panel) + URL to simply add a link to somewhere
    - title: boxtribute website
      url: https://www.boxtribute.org
    # Can be a Title (for the Nav panel) + description (for the Content panel)
    - title: Login to boxtribute web app
      url: https://www.app.boxtribute.org
    - title: Query API
      url: https://api.boxtribute.org
    - title: Query API changelog
      url: https://github.com/boxwise/boxtribute/releases
    - title: Terms of Service
      description: |
        In line with the Service Agreement and other related documents as signed with [Boxtribute](https://boxtribute.org) (Stichting Boxwise)
    - title: Authentication and Authorization
      description: |
        For using the API, you have to authenticate, and then are given a unique token holding your user information and permissions. You have to pass the token along when requesting data from the API.
        1. You need your username and password that you log in to `app.boxtribute.org` with. Pass it in the JSON part of a POST response to `api.boxtribute.org/token`, like `{"username": "my-email-address", "password": "PASSWORD"}`
        1. Copy the content of the `access_token` field of the response JSON
        1. Paste the token into the HTTP headers when sending a request to the API, like `{"Authorization": "Bearer TOKEN"}`
        1. When using the GraphQL explorer, paste the header into the respective field in the bottom left.

  # If you really want to hide the "Documentation by" at the bottom of your output, you can do so here
  # Default: false
  x-hidePoweredBy: false

  # If not using introspection.url OR servers[], you need to provide x-swaggerUrl
  # to satisfy the URL Swagger requirement. This allows for that.
  x-url: https://api.boxtribute.org