swagger.yaml

openapi: 3.0.0
info:
  title: SharePoint REST API
  description: SharePoint REST API endpoints documentation. 
  version: 1.0.0

servers:
  - url: https://{tenantName}.sharepoint.com/sites/{siteName}
    description: 'SharePoint site in the tenant.'
    variables:
      tenantName:
        default: contoso
        description: The name of your SharePoint tenant
      siteName:
        default: mySite
        description: The name of your SharePoint site
  - url: https://{tenantName}.sharepoint.com
    description: 'SharePoint root site of the tenant.'
    variables:
      tenantName:
        default: contoso
        description: The name of your SharePoint tenant

security:
  - bearerAuth: []
  - rtFaCookie: []
  - fedAuthCookie: []

components:

###############################################################################################
# Components - Security
###############################################################################################
  securitySchemes:
    rtFaCookie:
      type: apiKey
      in: cookie
      name: rtFa
    fedAuthCookie:
      type: apiKey
      in: cookie
      name: FedAuth
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

###############################################################################################
# Components - Schema definitions
###############################################################################################
  schemas:
    ListObject:
      type: object
      properties:
        Id: 
          type: string
          format: uuid
        Title:
          type: string
          example: 
            - 'MyList'
        ItemCount:
          type: number
          default: 842
        Created:
          type: string
          format: date-time

        # ... Other list properties

    ListObjectResponseJson:
      type: object
      properties:
        d:
          $ref: '#/components/schemas/ListObject'
      
    ListObjectResponseXml:
      type: object
      xml: 
        name: 'entry'
      properties:
        updated: 
          type: string
          format: date-time
        content:
          type: object
          properties:
            properties:
              $ref: '#/components/schemas/ListObject'

    ListsArrayResponseJson:
      type: object
      properties: 
        d:
          type: object
          properties: 
            results:
              type: array
              items:
                $ref: '#/components/schemas/ListObject'

    ListsArrayResponseXml:
      type: object
      xml:
          name: 'feed'
      properties: 
        updated: 
          type: string
          format: date-time
        content:
          $ref: '#/components/schemas/ListObjectResponseXml'


    ListItemsResponse:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/ListObject'

    ListItemObject:
      type: object
      additionalProperties: true
      properties:
        title:
          type: string
        Id:
          type: number
        Created:
          type: string
          format: date-time
        Modified:
          type: string
          format: date-time
        AuthorId:
          type: number
          description: Id of the author without requiring to $expand Author field properties
        EditorId:
          type: number

        # Properties requiring $select & $expand
        Author:
          $ref: '#/components/schemas/UserInfoItemObject'
        Editor:
          $ref: '#/components/schemas/UserInfoItemObject'
        # ... Other list item properties 
        # + custom list properties

    ListItemObjectResponseJson:
        type: object
        properties:
          d:
            $ref: '#/components/schemas/ListItemObject'

    ListItemObjectResponseXml:
      type: object
      xml: 
        name: 'entry'
      properties:
        updated: 
          type: string
          format: date-time
        content:
          type: object
          properties:
            properties:
              $ref: '#/components/schemas/ListItemObject'

    ListItemsArrayResponseJson:
      type: object
      properties: 
        d:
          type: object
          properties: 
            results:
              type: array
              items:
                $ref: '#/components/schemas/ListItemObject'
            __next:
              type: string
              format: url

    ListItemsArrayResponseXml:
      type: object
      xml: 
        name: 'feed'
      properties: 
        updated: 
          type: string
          format: date-time
        content:
          $ref: '#/components/schemas/ListItemObjectResponseXml'
        link:
          type: string
          format: url

    UserInfoItemObject:
      type: object
      properties:
        EMail:
          type: string
          format: email
        
        # TODO

    MenuState:
      type: object
      properties:
        AudienceIds:
          type: object
          properties:
            results:
              type:  array
              items:
                type: string
                format: uuid
                default: 00000000-0000-0000-0000-000000000000
        FriendlyUrlPrefix:
          type: string
        IsAudienceTargetEnabledForGlobalNav:
          type: boolean
        Nodes:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/MenuNode'
        SimpleUrl:
          type: string
        SPSitePrefix:
          type: string
        SPWebPrefix:
          type: string
        StartingNodeKey:
          type: string
        StartingNodeTitle:
          type: string
        Version:
          type: string
          format: date

    MenuNode:
      type: object
      properties:
        AudienceIds:
          type: object
          properties:
            results:
              type:  array
              default: []
              items:
                type: string
                format: uuid
        CurrentLCID:
          type: number
          pattern: '^\d{4}$' # 4 numbers
        CustomProperties:
          type: array
          items: 
            type: object
            properties:
              name:
                type: string
              key:
                type: string
        FriendlyUrlSegment:
          type: string
        IsDeleted:
          type: boolean
        IsHidden:
          type: boolean
        IsTitleForExistingLanguage:
          type: boolean
        Key: 
          type: string
          pattern: '^\d{4}$' # 4 numbers
        Nodes:
          type: array
          items:
            $ref: '#/components/schemas/MenuNode'
        NodeType:
          type: number
        OpenInNewWindow:
          type: boolean
        SimpleUrl:
          type: string
        Title:
          type: string
        Translations:
          type: array
          items:
            type: object
            #TODO

    NavigationNode:
      type: object
      properties:
        __metadata:
          type: object
          properties:
            type:
              type: string
              default: SP.NavigationNode
        AudienceIds:
          type: string
        CurrentLCID: 
          type: string
        IsExternal:
          type: boolean
        IsDocLib:
          type: boolean
        IsVisible:
          type: boolean
        Title:
          type: string
        Url: 
          type: string
          description: Url for the menu node. If label only, put 'http://linkless.header/' in Url.
      required:
        - __metadata
        - Title
        - Url
        - IsExternal
      example:
        __metadata: 
            type: SP.NavigationNode
        Title: My node
        Url: /myPage.aspx
        IsExternal: false


    NavigationNodeResponseJson:
      type: object
      properties:
        d:
          type: object
          properties:
            NavigationNode:
              $ref: '#/components/schemas/NavigationNode'


    MenuStateResponseJson:
      type: object
      properties:
        d:
          type: object
          properties:
            MenuState:
              $ref: '#/components/schemas/MenuState'

    ErrorResponseJson:
      type: object
      xml: 
        name: error
      properties:
        code:
          type: string
        message:
          type: object
          properties: 
            lang:
              type: string
              default: 'fr-FR'
            value:
              type: string

    ErrorResponseXml:
      type: object
      xml: 
        name: error
      properties:
        code:
          type: string
        message:
          type: object
          properties: 
            lang:
              type: string
              default: 'fr-FR'
              xml:
                attribute: true

###############################################################################################
# Components - Parameters
###############################################################################################
  parameters:
# Query params
    select:
      name: $select
      description: Use the `$select` query option to specify which fields to return for a given list, list item, or other SharePoint object represented by an entity set. You can use `$select=*` to return all available fields.
      in: query
      required: false
      schema:
        type: string
        example:
          - "Id,Title"
          - "Author"

    orderby:
      name: $orderby
      description: Use the `$orderby` query option to specify how to sort the items in your query return set. To sort by multiple fields, specify a comma-separated list of fields. You can also specify whether to sort the items in ascending or descending order by appending the asc or desc keyword to your query.
      in: query
      required: false
      schema:
        type: number
        example:
          - "Id"
          - "Title"

    top: 
      name: $top
      description: "The `$top` option enables you to select the first **n** items of the return set for return. For example, the following URI requests that only the first 10 items in the prospective return set actually be returned: `$top=10`"
      in: query
      required: false
      schema:
        type: number
        example:
          - 100

    skip:
      name: $skip
      description: The `$skiptoken` query option enables you to skip over items until the specified item is reached and return the rest.
      in: query
      required: false
      schema:
        type: number
        example:
          - 100

    filter:
      name: $filter
      description: Use the `$filter` query option to select which items to return. [OData query operators supported in the SharePoint REST service](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/use-odata-query-operations-in-sharepoint-rest-requests#odata-query-operators-supported-in-the-sharepoint-rest-service) lists the filter query comparison options and functions you can use with the SharePoint REST service.
      in: query
      required: false
      schema:
        type: string
        example:
          - "Id eq 1"
          - "startswith(Title, 'XX')"

    expand: 
      name: $expand
      description: "Use the `$expand` query option to expand fields. The syntax for `$expand` operator is as follows: `$expand= Field/Id`"
      in: query
      required: false
      schema:
        type: string
        example:
          - "Id,Title"
          - "Author"

# Path params
    listTitle:
      name: listTitle
      description: "Display name of list."
      in: path
      required: true
      schema:
        type: string
        default: 'MyList'

    listGUID:
      name: listGUID
      description: "GUID of list."
      in: path
      required: true
      schema:
        type: string
        format: uuid

    itemId:
      name: itemId
      description: "Id of the item."
      in: path
      required: true
      schema:
        type: string
        format: number

    termGUID:
      name: termGUID
      description: "GUID of the term."
      in: path
      required: true
      schema:
        type: string
        format: guid

    termSetGUID:
      name: termSetGUID
      description: "GUID of the term set."
      in: path
      required: true
      schema:
        type: string
        format: guid

    nodeId:
      name: nodeId
      description: "Id of the node."
      in: path
      required: true
      schema:
        type: string
        format: number

# Other Params
    Content-Type:
      name: Content-Type
      description: needed when sending json body.
      required: true
      in: header
      schema: 
        type: string
        default: application/json


###############################################################################################
# Components - Responses
###############################################################################################
  responses:
    BadRequest:
      description: Bad request
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ErrorResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseJson'
    Unauthorized:
      description: Unauthorized
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ErrorResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseJson'

    UnauthorizedOperation:
      description: Unauthorized operation
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ErrorResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseJson'

    NotFound:
      description: Not found
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ErrorResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseJson'

    NoContent:
      description: No Content. 

    LastItemModifiedDate:
      description: Returns the LastItemModifiedDate for site.
      content:
        application/atom+xml:
          schema:
            type: string
            xml:
              name: d:LastItemModifiedDate
            format: date-time
        application/json:
          schema:
            type: object
            properties:
              d: 
                type: object
                properties:
                  LastItemModifiedDate:
                    type: string
                    format: date-time

    LastItemUserModifiedDate:
      description: Returns the LastItemUserModifiedDate for site.
      content:
        application/atom+xml:
          schema:
            type: string
            xml:
              name: d:LastItemUserModifiedDate
            format: date-time
        application/json:
          schema:
            type: object
            properties:
              d: 
                type: object
                properties:
                  LastItemUserModifiedDate:
                    type: string
                    format: date-time


    ListObject:
      description: List object response
      content: 
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ListObjectResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ListObjectResponseJson'

    ListsArray:
      description: List array response
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ListsArrayResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ListsArrayResponseJson'

    ListItemObject:
      description: List item object response
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ListItemObjectResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ListItemObjectResponseJson'

    ListItemsArray: 
      description: Array of list items response
      content:
        application/atom+xml:
          schema:
            $ref: '#/components/schemas/ListItemsArrayResponseXml'
        application/json:
          schema:
            $ref: '#/components/schemas/ListItemsArrayResponseJson'

    MenuState:
      description: Navigation menu objects
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MenuStateResponseJson'

    NavigationNode:
      description: Navigation node object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NavigationNodeResponseJson'

###############################################################################################
# Components - Callbacks
###############################################################################################
  # callbacks:


###############################################################################################
# Tags
###############################################################################################
tags:
  - name: site
    description: |
      Query site information.
  - name: lists
    description: |
      Query lists.
  - name: list items
    description: |
      Query list items.  
      Any list query can be used.  
      **Note**: `Author` & `Editor` fields require `$select` & `$expand` to view full details.
  - name: pages
    description: |
      Working with pages
  - name: files and folders
    description: |
      Working with files and folders
  - name: terms
    description: | 
      Working with terms of term store and managed metadata
  - name: navigation
    description: |
      Working with site navigation menu. 

###############################################################################################
# Paths
###############################################################################################
paths:
  /_api/web/LastItemModifiedDate:
    get:
      summary: Get the last activity date for site.
      description: Site's last activity date will be updated, when a file is updated or added, list item is updated or added, when a user visits the site. 
      tags:
        - site
      responses:
        '200':
          $ref: '#/components/responses/LastItemModifiedDate'

  /_api/web/LastItemUserModifiedDate:
    get:
      summary: Gives the last date when a list / library was updated.
      tags:
        - site
      responses:
        '200':
          $ref: '#/components/responses/LastItemUserModifiedDate'


  /_api/lists:
    get:
      summary: Get all the lists from site
      tags:
        - lists
      parameters: 
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/expand'

      responses:
        '200':
          $ref: '#/components/responses/ListsArray'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'
          
  /_api/lists/getByTitle('{listTitle}'):
    get:
      summary: Get list by title
      tags:
        - lists
      parameters:
        - $ref: '#/components/parameters/listTitle'
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/expand'
      responses:
        '200':
          $ref: '#/components/responses/ListObject'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/lists/getById(guid'{listGUID}'):
    get:
      summary: Get list by GUID
      tags: 
        - lists
      parameters:
        - $ref: '#/components/parameters/listGUID'
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/expand'
      responses:
        '200':
          $ref: '#/components/responses/ListObject'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/lists/getByTitle('{listTitle}')/items:
    get:
      summary: Get items from list by title
      tags: 
        - list items
      parameters:
        - $ref: '#/components/parameters/listTitle'
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/expand'
      responses:
        '200':
          $ref: '#/components/responses/ListItemsArray'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/lists/getByTitle('{listTitle}')/items({itemId}):
    get:
      summary: Get items from list by title
      tags: 
        - list items
      parameters:
        - $ref: '#/components/parameters/listTitle'
        - $ref: '#/components/parameters/itemId'
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/expand'
      responses:
        '200':
          $ref: '#/components/responses/ListItemObject'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/Navigation/MenuState:
    post:
      summary: Get menu items
      tags: 
        - navigation
      parameters:
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/expand'
      responses:
        '200':
          $ref: '#/components/responses/MenuState'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'
  
  /_api/Web/Navigation/QuickLaunch:
    # Cannot GET this url 
    post:
      summary: Add to navigation menu
      tags:
        - navigation
      parameters:
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/Content-Type'
      requestBody:
        description: Details for the menu item to add.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigationNode'
      responses:
        '200':
          $ref: '#/components/responses/NavigationNode'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/Web/Navigation/GetNodeById({nodeId})/Children:
    # Cannot GET this url 
    post:
      summary: Add node bellow existing navigation menu node
      tags:
        - navigation
      parameters:
        - $ref: '#/components/parameters/select'
        - $ref: '#/components/parameters/Content-Type'
        - $ref: '#/components/parameters/nodeId'
      requestBody:
        description: Details for the menu item to add.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigationNode'
      responses:
        '200':
          $ref: '#/components/responses/NavigationNode'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/v2.1/termStore/sets/{termSetGUID}/terms/{termGUID}:
    delete:
      summary: Delete term
      tags:
        - terms
      parameters:
        - $ref: '#/components/parameters/termSetGUID'
        - $ref: '#/components/parameters/termGUID'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/web/GetFolderByServerRelativeUrl('{fileServerRelativeUrl}')/files:
   # fileServerRelativeUrl : site relative 
    get: #TODO
      summary: TODO
      tags:
        - files and folders
      responses:
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'

  /_api/web/folders:
    get: #TODO
      summary: TODO
      tags:
        - files and folders
      responses:
        '400': 
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/UnauthorizedOperation'
        '404':
          $ref: '#/components/responses/NotFound'