Allura/docs/api-rest/traits.yaml

#       Licensed to the Apache Software Foundation (ASF) under one
#       or more contributor license agreements.  See the NOTICE file
#       distributed with this work for additional information
#       regarding copyright ownership.  The ASF licenses this file
#       to you under the Apache License, Version 2.0 (the
#       "License"); you may not use this file except in compliance
#       with the License.  You may obtain a copy of the License at
#
#         http://www.apache.org/licenses/LICENSE-2.0
#
#       Unless required by applicable law or agreed to in writing,
#       software distributed under the License is distributed on an
#       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#       KIND, either express or implied.  See the License for the
#       specific language governing permissions and limitations
#       under the License.

searchable:
    queryParameters:
      query:
        description: |
          JSON array [{"field1","value1","operator1"},{"field2","value2","operator2"},...,{"fieldN","valueN","operatorN"}] <<description>>
        example: |
          <<example>>
orderable:
    queryParameters:
      orderBy:
        description: |
          Order by field: <<fieldsList>>
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        default: desc
        required: false
pageable:
    queryParameters:
      page:
        description: Skip over a number of elements by specifying a starting page
        type: integer
        required: false
        example: 0
        default: 0
      limit:
        description: Limit the number of elements on the response "page"
        type: integer
        required: false
        example: 10
        default: 25
permissionTestable:
    description: |
      **Endpoints**
      Permissions can be checked at three levels:
      1. **Neighborhood:** `/rest/p/has_access`
      2. **Project:** `/rest/p/project_name/has_access`
      3. **Tool:** `/rest/p/project_name/mount_point/has_access`

      ---

      It is only available to users that have 'admin' permission for corresponding neighborhood/project/tool. It requires user and perm parameters and will return JSON dict with result key, which contains boolean value, indicating if given user has perm permission to the neighborhood/project/tool.

      E.g.:
      **GET** `/rest/p/test/wiki/has_access?user=admin1&perm=create`
      *returns* { result: true }
      **GET** `/rest/p/test/wiki/has_access?user=user01&perm=create`
      *returns* { result: false }

    queryParameters:
      user:
        type: string
        example: heiths
        required: true
        description: The username to check
bearerAuth:
    # This can also be done with ?access_token=
    # But it's simpler in the docs / Try It interface to just show one option
    # and using the header method keeps it separate from query params that the individual API endpoints use
    headers:
      Authorization:
        description: |
          Optional.  Authenticate yourselve with a token from https://forge-allura.apache.org/auth/oauth/
          Use it here like: `Bearer 5d79e800a36bf602314d`
        type: string
        pattern: "^Bearer [0-9a-f]+$"