adds support for deprecation

[baywet]

fixes #113

This PR sets deprecated to true on operations that depend on annotables with an annotation of term Org.OData.Core.V1.Revisions and of kind Org.OData.Core.V1.RevisionKind/Deprecated (see the linked issue for more details).

It will also add and extension to the operation to convey the additional information from the annotation like

/People/$count:
    get:
      summary: Get the number of the resource
      operationId: Get.Count.People
      responses:
        '200':
          description: The count of the resource
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ODataCountResponse'
        default:
          $ref: '#/components/responses/error'
      deprecated: true
      x-ms-deprecation:
        removalDate: '2023-03-15T00:00:00.0000000'
        date: '2021-08-24T00:00:00.0000000'
        version: 2021-05/people
        description: The People API is deprecated and will stop returning data on March 2023. Please use the new newPeople API.

The flag + extension will be added to any operation if any path segment in the path is annotated including:

• parent entity sets
• parent singleton
• parent navigation properties
• the type or base type of the nav prop/singleton/entity set

Note: depending on merge order, #149 will need to be updated to return the target type in the annotables for the segment

[xuzhg]

the namespace looks have different pattern comparing to the existing?

[baywet]

if it were up to me, I'd have converted all the existing files to this new format, you get more real-estate on the screen. But doing so might generate tons of conflicts since we have multiple people contributing at this time.
So my compromise was to do it only for new files, so they are future proof, and maybe later we can have a PR that updates the existing files once we're done with our batch of modifications.

[xuzhg]

alignment the codes, tab -> 4 whitespaces

[xuzhg]

It seems you can implement the default "GetAnnotables()" at the base class to return an empty Enumerable. Only override the method in the class that should be overridden?

[baywet]

The reason why I didn't make it virtual is because I want the compiler to error out in case we forgot a segment type instead of silently pass. This is going to come handy as we coordinate with PRs that add other segment types. But it could mean a breaking change for people whom inherited from the OData segment class, so I'm willing to compromise on this one. What do you think?

[xuzhg]

The deprecation looks for the ODataPath, not a certain Segment in the Path, right?

[baywet]

each segment can have deprecation information, which means a path can have multiple deprecations. Then the path will take the uppermost (shortest path) deprecation.

[baywet]

a good example of that is me/mailFolders/{id}/messages/{id}/attachments where in theory:

• the user type (or a parent type) could be deprecated
• the me singleton could be depracated
• the mailFolder (or a parent type) could be deprecated
• the mailFolders navigation property could be deprecated
• ...

Assuming we have deprecation for all of those, the deprecation for the path that will be used, is the one from user, if user is not deprecated, the one from me, if not me, mailfolder, etc....

[xuzhg]

Look good to me.