API Genie

--generate sends one request per operation of --spec, checked as that operation: path parameters, required query, header and cookie parameters, and a body of the first media type (JSON first), each from the document’s examples or generated from its schemas (readOnly properties left out). An XML media type gets an XML body, written as the schema’s xml objects describe it. The URL is --base-url (or the document’s first server) followed by the operation’s path. Request files and --generate can be combined.

With an AsyncAPI document, --generate sends one region per WebSocket or MQTT channel, bound with # @channel (and # @operation when the channel has one receive operation): WebSocket channels at --base-url (ws://host:port) followed by the channel’s address, MQTT channels at --mqtt-url, publishing to the address and subscribing to it when the application sends there. Parameters of the address take their default, first enum value or example. The messages are those of the channel’s receive operations, from their examples or generated from their schemas; MQTT regions get the # @property lines of the first one’s bindings and headers (correlation data and response topics generated from their schemas, user properties from the first example’s headers or generated); # @expect is the number of replies, plus one when the application sends on the channel. HTTP channels get one request per operation, bound with # @operation, at --base-url (a ws:// URL is taken as http://) followed by the channel’s address: a receive operation’s with its HTTP binding’s method and its first message (an example, else generated) as the body, a send operation’s a GET. Channels without an address are left out with a warning, as are the channels of a protocol whose URL wasn’t given.

Kafka channels get one KAFKA region per operation at --kafka-url, bound with # @operation. A receive operation’s region produces its first message (an example, else generated) to the channel’s topic, with a key made from the message’s Kafka binding and # @property headers from its headers; it reads the reply’s topic for one record (# @expect 1) when the operation has a reply, and ends once the record is produced otherwise. A send operation’s region only reads the topic, for one record the application produces.

AMQP channels get one AMQP region per operation at --amqp-url, bound with # @operation. A receive operation’s region publishes its first message to the channel’s exchange and routing key (a queue channel’s queue through the default exchange) with the properties its bindings say and its headers; it reads the reply’s channel, its queue or a queue bound to its exchange, when the operation has a reply. A send operation’s region reads the channel for one message the application publishes.

With a .proto file, --generate sends one GRPC request per method of its services (the built-in reflection and health services aside) to --base-url, which is then required and is HOST:PORT, grpc://HOST:PORT or grpcs://HOST:PORT (TLS). The message is generated from the input type as the mock generates answers ({} for google.protobuf.Empty): REQUIRED fields set, OUTPUT_ONLY fields left out. Client- and bidi-streaming methods get a stream of two generated messages.

With a GraphQL schema, --generate sends one GRAPHQL request per field of Query, Mutation and Subscription (deprecated fields left out), named after the field (Query.book) and bound to its operation (QueryBook). A subscription goes over graphql-ws with # @expect 1: the first event is enough. Required arguments get values made up from their types as apigenie-server makes up values (the scalar’s or the argument’s name: a UUID for ID, an email for email, a date for DateTime, an enum value that isn’t deprecated, an input object with its required fields); optional ones are left out. The selection set has the leaf fields without required arguments, objects two levels down, and __typename with a fragment per type of an interface or a union. --base-url is required: it is the endpoint, with /graphql added when it has no path.

mutation MutationAddBook {
  addBook(input: {title: "Twenty Years After", genre: POETRY}) {
    id
    title
    genre
    pages
    author {
      id
      name
      email
    }
  }
}

Generated requests