How to specify in OpenAPI adding a user to a group?

Question

I am attempting to create a custom connector for MS Flow\Logic Apps that uses some of the REST endpoints that are part of the microsoft graph but am having trouble in understanding how to document the API in OpenAPI 2.0 specification

The MS documentation

https://docs.microsoft.com/en-us/graph/api/group-post-owners?view=graph-rest-1.0#example

says to include

"@odata.id": "https://graph.microsoft.com/v1.0/users/{id}"

as a $ref parameter as part of the request body

but how do I document this in OpenAPI 2.0 specification?

This is what I have got so far...

'/groups/{team-id}/owners':
    post:
      tags:
        - teams.team
      summary: Add a new owner to the team
      operationId: teams.AddOwner
      consumes:
        - application/json
      parameters:
        - name: team-id
          in: path
          required: true
          type: string
          description: Id of the MS team
          x-ms-summary: Team Id
          x-ms-visibility: important
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              userId:
                type: string
                description: Id of the user to be added as an owner to the team
                x-ms-summary: User Id
                x-ms-visibility: important
              '@odata.id':
                default: https://graph.microsoft.com/v1.0/users/{userId}
      responses:
        '204':
          description: Success
        default:
          $ref: '#/responses/error'
      x-ms-docs-operation-type: operation

When I submit the above to create the custom connector I get the following error

Specified file does not match OpenAPI 2.0 specification: 'JSON is valid against no schemas from 'oneOf'. Path 'paths./groups/{team-id}/owners.post.parameters[1]'.'

EDIT

I have updated the OpenAPI to look like below

This means that I can import and use this... but I have to construct the URL for the @odata.id parameter manually in the workflow!

"@odata.id": "https://graph.microsoft.com/v1.0/users/{id}"

'/groups/{team-id}/owners/$ref':
    post:
      tags:
        - teams.team
      summary: Add a new owner to the team
      operationId: teams.AddOwner
      consumes:
        - application/json
      parameters:
        - name: team-id
          in: path
          required: true
          type: string
          description: Id of the MS team
          x-ms-summary: Team Id
          x-ms-visibility: important
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              '@odata.id':
                title: User Id
                type: string
                x-ms-summary: User Id
                x-ms-visibility: important
      responses:
        '204':
          description: Success
        default:
          $ref: '#/responses/error'
      x-ms-docs-operation-type: operation

EDIT

How should I be specifying this to get the userId?

How do I specify the body parameter correctly?

Is there any documentation\examples on how to do this?

Any help would be much appreciated

Thanks in advance

Pete

MS Graph OpenAPI definition is available at github.com/microsoftgraph/microsoft-graph-openapi — Helen
@Helen Thanks. Unfortunately it doesn't document this operation. It is also specified as OpenAPI 3+ which is not currently valid for custom connectors in MS Flow — Pete

SeaDude SeaDude · Accepted Answer · 2019-05-09T03:35:08

One of the easiest ways I’ve found to create a PowerApps Custom Connector is to:

Use Postman to craft a working request
Build the Custom Connector from Blank
Test in the Custom Connector “Test” area

Then, you can download the Swagger file if you need it. Basically, let PowerApps build the Swagger file FOR YOU instead of the other way around.

Here is a YouTube video of the method I like to use.

https://m.youtube.com/watch?v=-wQljWG35zM

How to specify in OpenAPI adding a user to a group?

1 Answers