-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This command allows you to generate a mock API proxy from an OpenAPI 3.x spec. The generated mock API proxy supports the following features: * Request validation (`Mock-Validate-Request` header) * Specific & Dynamic response status (`Mock-Status` header) * Specific & Dynamic response content-type (`Accept` header) * Specific & Dynamic response examples (`Mock-Fuzz`) * Random generator seeding (`Mock-Seed` header)
- Loading branch information
Showing
16 changed files
with
2,276 additions
and
93 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| // Copyright 2024 Google LLC | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| package mock | ||
|
|
||
| import ( | ||
| "github.com/apigee/apigee-go-gen/cmd/apigee-go-gen/mock/oas" | ||
| "github.com/spf13/cobra" | ||
| ) | ||
|
|
||
| var Cmd = &cobra.Command{ | ||
| Use: "mock", | ||
| Short: "Generate a mock API proxy", | ||
| } | ||
|
|
||
| func init() { | ||
| Cmd.AddCommand(oas.Cmd) | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| // Copyright 2024 Google LLC | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| package oas | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "github.com/apigee/apigee-go-gen/pkg/common/resources" | ||
| "github.com/apigee/apigee-go-gen/pkg/flags" | ||
| "github.com/apigee/apigee-go-gen/pkg/mock" | ||
| "github.com/spf13/cobra" | ||
| ) | ||
|
|
||
| var input = flags.NewString("") | ||
| var output = flags.NewString("") | ||
|
|
||
| var Cmd = &cobra.Command{ | ||
| Use: "oas", | ||
| Short: "Generate a mock API proxy from an OpenAPI 3.X spec", | ||
| Long: Usage(), | ||
| RunE: func(cmd *cobra.Command, args []string) error { | ||
| return mock.GenerateMockProxyBundle(string(input), string(output)) | ||
| }, | ||
| } | ||
|
|
||
| func init() { | ||
| Cmd.Flags().SortFlags = false | ||
| Cmd.Flags().VarP(&input, "input", "i", `path to input spec (e.g. ./path/to/spec.yaml"`) | ||
| Cmd.Flags().VarP(&output, "output", "o", `OpenAPI spec to use"`) | ||
|
|
||
| _ = Cmd.MarkFlagRequired("input") | ||
| _ = Cmd.MarkFlagRequired("output") | ||
| } | ||
|
|
||
| func Usage() string { | ||
| usageText := ` | ||
| This command generates a mock API proxy bundle from an OpenAPI 3.X Spec. | ||
| The mock API proxy includes the following features: | ||
| %[1]s | ||
| ` | ||
|
|
||
| mockFeatures, err := resources.FS.ReadFile("mock_features.txt") | ||
| if err != nil { | ||
| panic(err) | ||
| } | ||
|
|
||
| return fmt.Sprintf(usageText, mockFeatures) | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,165 @@ | ||
| # Mock OAS | ||
| <!-- | ||
| Copyright 2024 Google LLC | ||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| See the License for the specific language governing permissions and | ||
| limitations under the License. | ||
| --> | ||
|
|
||
| This command generates a mock Apigee API proxy from your OpenAPI 3.X specification. | ||
|
|
||
| This mock API proxy dynamically creates responses based on the information within your spec, allowing for quick and easy API mocking. | ||
|
|
||
| ## Usage | ||
|
|
||
| The `mock oas` command takes the following parameters: | ||
|
|
||
| * `--input string` | ||
|
|
||
| * This is the path to the OpenAPI spec file to use (either YAML or JSON) | ||
|
|
||
| * You can use `--input -` to read from standard input (stdin) | ||
|
|
||
| * Internally, the OpenAPI spec is converted to JSON when generating the mock API proxy. | ||
|
|
||
|
|
||
| * `--output string` | ||
|
|
||
| * This is the location where the mock API proxy bundle will be created. | ||
|
|
||
|
|
||
| The tool can create the mock API proxy either as a directory or as a zip. e.g. | ||
|
|
||
| * If you provide a path like this `--output=./path/to/apiproxy.zip`, then a proxy bundle zip is created. | ||
| * If you provide a path like this `--output=./path/to/apiproxy`, then a proxy bundle directory is created | ||
|
|
||
|
|
||
| ## Mock API Proxy Features | ||
|
|
||
| The generated mock API proxy supports the following features listed below. | ||
|
|
||
|
|
||
| ### Request Validation | ||
|
|
||
| By default, the mock API proxy validates the incoming requests against your OpenAPI specification. | ||
| This ensures that the headers, query parameters, and request body all conform to the defined rules. | ||
|
|
||
| This helps you catch errors in your client code early on. | ||
|
|
||
| You can disable request validation by passing the header `Mock-Validate-Request: false`. | ||
|
|
||
| ### Dynamic Response Status Codes | ||
|
|
||
| The mock API proxy automatically generates different status codes for your mock API responses. Here's how it works: | ||
|
|
||
| * **Prioritizes success:** If the operation allows HTTP 200 status code, the proxy will use it. | ||
| * **Random selection:** If HTTP 200 is not allowed for a particular operation, the proxy will pick a random status code from those allowed. | ||
|
|
||
| **Want more control?** You can use headers to select response the status code: | ||
|
|
||
| * **Specific status code:** Use the `Mock-Status` header in your request and set it to the desired code (e.g., `Mock-Status: 404`). | ||
| * **Random status code:** Use the `Mock-Fuzz: true` header to get a random status code from your spec. | ||
|
|
||
| If you use both `Mock-Status` and `Mock-Fuzz`, `Mock-Status` takes precedence. | ||
|
|
||
| ### Content-Type Negotiation | ||
|
|
||
| The mock API proxy automatically selects the `Content-Type` for responses: | ||
|
|
||
| * **JSON preferred:** If the operation allows `application/json`, the proxy will default to using it. | ||
| * **Random selection:** If `application/json` is not available, the proxy will randomly choose from the other media types available for that operation. | ||
|
|
||
| **Want more control?** You can use headers to select the response Content-Type: | ||
|
|
||
| * **Standard `Accept` header:** You can use the standard `Accept` header in your request to request a specific media type (e.g., `Accept: application/xml`). | ||
| * **Random media type:** Alternatively, use the `Mock-Fuzz: true` header to have the proxy select a random media type the available ones. | ||
|
|
||
| If you use both `Accept` and `Mock-Fuzz`, the `Accept` header will take precedence. | ||
|
|
||
|
|
||
| ### Dynamic Response Bodies | ||
|
|
||
| The mock API proxy can generate realistic response bodies based on your OpenAPI spec. | ||
|
|
||
| Here's how it determines what to send back for any particular operation's response (in order): | ||
|
|
||
| 1. **Prioritizes `example` field:** If the response includes an `example` field, the proxy will use that example. | ||
|
|
||
| 2. **Handles multiple `examples`:** If the response has an `examples` field with multiple examples, the proxy will randomly select one. You can use the `Mock-Example` header to specify which example you want (e.g., `Mock-Example: my-example`). | ||
|
|
||
| 3. **Uses schema examples:** If no response examples are provided, but the schema for the response has an `example`, the proxy will use that. | ||
|
|
||
| 4. **Generates from schema:** As a last resort, the proxy will generate a random example based on the response schema. This works for JSON, YAML, and XML. | ||
|
|
||
| You can use the `Mock-Fuzz: true` header to force the proxy to always generate a random example from the schema, even if other examples are available. | ||
|
|
||
| ### Making Mock API Responses Repeatable | ||
|
|
||
| The mock API proxy uses a special technique to make its responses seem random, while still allowing you to get the same response again if needed. Here's how it works: | ||
|
|
||
| * **Pseudo-random numbers:** The "random" choices the proxy makes (like status codes and content) are actually generated using a pseudo-random number generator (PRNG). This means the responses look random, but are determined by a starting value called a "seed." | ||
|
|
||
| * **Unique seeds:** Each request uses a different seed, so responses vary. However, the seed is provided in a special response header called `Mock-Seed`. | ||
|
|
||
| * **Getting the same response:** To get an identical response, simply include the `Mock-Seed` header in a new request, using the value from a previous response. This forces the proxy to use the same seed and generate the same "random" choices, resulting in an identical response. | ||
|
|
||
| This feature is super helpful for: | ||
|
|
||
| * **Testing:** Ensuring your tests always get the same response. | ||
| * **Debugging:** Easily recreating specific scenarios to pinpoint issues in application code. | ||
|
|
||
| Essentially, by using the `Mock-Seed` header, you can control the randomness of the mock API responses, making them repeatable for testing and debugging. | ||
|
|
||
| ### Example Generation from JSON Schemas | ||
|
|
||
| The following fields are supported when generating examples from a JSON schema: | ||
|
|
||
| * `$ref` - local references are followed | ||
| * `$oneOf` - chooses a random schema | ||
| * `$anyOf` - chooses a random schema | ||
| * `$allOf` - combines all schemas | ||
| * `obect` type | ||
| * `required` field - all required properties are chosen | ||
| * `properties` field - a random set of properties is chosen | ||
| * `additionalProperties` field - only used when there are no `properties` defined | ||
| * `array` type | ||
| * `minItems`, `maxItems` fields - array length chosen randomly between these values | ||
| * `items` field - determines the type of array elements | ||
| * `prefixItems` (not supported yet) | ||
| * `null` type | ||
| * `const` type | ||
| * `boolean` type - true or false randomly chosen | ||
| * `string` type | ||
| * `enum` field - a random value is chosen | ||
| * `pattern` field (not supported yet) | ||
| * `format` field | ||
| * `date-time` format | ||
| * `date` format | ||
| * `time` format | ||
| * `email` format | ||
| * `uuid` format | ||
| * `uri` format | ||
| * `hostname` format | ||
| * `ipv4` format | ||
| * `ipv6` format | ||
| * `duration` format | ||
| * `minLength`, `maxLength` fields - string length chosen randomly between these values | ||
| * `integer` type | ||
| * `minimum`, `maximum` fields - integer value chosen randomly between these values | ||
| * `exclusiveMinimuim` field (boolean, JSON-Schema 4) | ||
| * `exclusiveMaximum` field (boolean, JSON-Schema 4) | ||
| * `multipleOf` field | ||
| * `number` type | ||
| * `minimum`, `maximum` fields - integer value chosen randomly between these values | ||
| * `exclusiveMinimuim` field (boolean, JSON-Schema 4) | ||
| * `exclusiveMaximum` field (boolean, JSON-Schema 4) | ||
| * `multipleOf` field |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.