Represent messages on queues

[jayshao]

While not strictly supported by Swagger today... I would love to see an extension that let us re-use models and the editors to represent messages placed onto or read off of queues (e.g. Kinesis. SNS, Kafka, etc.)

Ideally these would be very similar to the current endpoints - except conceptually I think broken out as a separate category of events - with some way to specify where the events are placed. In practice I think vs. REST semantics there is probably also a stronger distinction between producers and consumers - and both are interesting to be able to use to document a service or as an API (e.g. This API listens on XX queue)

More details:

In our specific example - this is inspired by serverless.com's serverless.yml handling of triggers for function invocation (see: https://serverless.com/framework/docs/providers/aws/guide/serverless.yml/)

As some examples, here are the events a function can bind too - though some are AWS specific and could probably be better generalized:

events: # The Events that trigger this Function

• http: # This creates an API Gateway HTTP endpoint which can be used to trigger this function. Learn more in "events/apigateway" path: users/create # Path for this endpoint method: get # HTTP method for this endpoint cors: true # Turn on CORS for this endpoint, but don't forget to return the right header in your response private: true # Requires clients to add API keys values in the x-api-key header of their request authorizer: # An AWS API Gateway custom authorizer function name: authorizerFunc # The name of the authorizer function (must be in this service) arn: xxx:xxx:Lambda-Name # Can be used instead of name to reference a function outside of service resultTtlInSeconds: 0 identitySource: method.request.header.Authorization identityValidationExpression: someRegex
• s3: bucket: photos event: s3:ObjectCreated:* rules:
  • prefix: uploads/
  • suffix: .jpg
• schedule: rate: rate(10 minutes) enabled: false input: key1: value1 key2: value2 stageParams: stage: dev
• sns: topicName: aggregate displayName: Data aggregation pipeline
• stream: arn: arn:aws:kinesis:region:XXXXXX:stream/foo batchSize: 100 startingPosition: LATEST enabled: false
• alexaSkill
• alexaSmartHome: appId: amzn1.ask.skill.xx-xx-xx-xx enabled: true
• iot: name: myIoTEvent description: An IoT event enabled: true sql: "SELECT * FROM 'some_topic'" sqlVersion: beta
• cloudwatchEvent: event: source:
  • "aws.ec2" detail-type:
  • "EC2 Instance State-change Notification" detail: state:
    • pending

      Note: you can either use "input" or "inputPath"

      input: key1: value1 key2: value2 stageParams: stage: dev inputPath: '$.stageVariables'

• cloudwatchLog: logGroup: '/aws/lambda/hello' filter: '{$.userIdentity.type = Root}'
• cognitoUserPool: pool: MyUserPool trigger: PreSignUp

[jayshao]

We played with some conventions for modelling these as groups of endpoints (e.g. creating a tag like 'events') - which might be a workaround, though that doesn't quite feel right.

[jayshao]

Thoughts:

• some UI treatment for hiding request or response blocks might make something like this fairly clean
• perhaps some custom HTTP method like semantics? e.g. Publish / Subscribe? We could overload PUT / GET - but again, that seems somewhat misleading

[marbemac]

Would the ability to define schemas and reference them in your docs go a long way towards accomplishing this goal?

Basically, this: https://github.com/stoplightio/desktop/issues/87

[jayshao]

It would go a long way. Putting them in the Swagger files would be nice... but isn't strictly required - developer portal - definitely. Some convention with Swagger extensions might be really nice - but maybe I need to persuade the world to come around to my PoV first :)

On Thu, Nov 30, 2017 at 12:45 PM Marc MacLeod notifications@github.com wrote:

Would the ability to define schemas and reference them in your docs go a long way towards accomplishing this goal?

Basically, this: #87 https://github.com/stoplightio/desktop/issues/87

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/stoplightio/desktop/issues/90#issuecomment-348265307, or mute the thread https://github.com/notifications/unsubscribe-auth/AAMitxuu3lkeSKORNAvCbiScVf1XcVoGks5s7umngaJpZM4Qvbry .

--

Jason Shao

Head of Engineering

T: 212 644-6200 x9536

M: 732 221-9771

jason.shao@intersection.com

@jayshao https://twitter.com/jayshao

Intersection

10 Hudson Yards 26th Floor New York NY 10001

intersection.com

[marbemac]

You'll be able to reference the standalone schemas from swagger files as well as hub files.

In Q1 '18 we're introducing plugins that will allow the community to do stuff like define their own re-usable extensions. So, you could create a plugin that defines extensions for the messaging stuff in OAS 2 files, and then try to share it around the SL community :).