> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wiremock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import & Export - Swagger and OpenAPI

> Generate your mock API automatically from a Swagger or OpenAPI definition.

Swagger / OpenAPI is undoubtedly the most widely used description language for REST and REST-like APIs. WireMock Cloud supports automatic generation of mock APIs from imported Swagger and OpenAPI specifications.

See [Import and Export Overview](/import-export/overview) for basic importing instructions via the UI and [Importing and Export via the API](../import-export/api) for directions on automating
imports via WireMock Cloud's API.

## Customising the import

When importing from a Swagger/OpenAPI spec, it's often useful to be able to control
how certain aspects of the generated stubs are produced. WireMock Cloud supports a number
of extension attributes that can be added to your spec document for this purpose.

### Specifying URL path and query parameters

When WireMock Cloud converts a response example to a stub, by default it will generate random values for URL path and query parameters.

However, if a response uses the multiple example format, you can specify the exact parameter values you wish to be required
by the stub. This can be useful if your test cases or application under test expects specific
responses to be available in your mock API.

For instance, given the following Open API path element:

```yaml theme={null}
/people/{id}:
    description: People by ID
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string

    get:
      description: Get a person
      parameters:
        - name: fields
          in: query
          required: true
          schema:
            type: string
            enum:
              - full
              - summary

      responses:
        '200':
          description: People search returned successfully
          content:
            application/json:
              examples:
                one:
                  summary: First example
                  x-parameter-values:
                    id: abc123
                    fields: summary
                  value: |
                    { "name": "John" }

                two:
                  summary: Second example
                  x-parameter-values:
                    id: cba321
                    fields: full
                  value: |
                    { "name": "Jeff", id: "cba123" }
```

Two stubs will be created from the above example.
One will have a URL path equal to `/people/abc123` and a required query parameter of `fields=summary`.
The other will have a URL path equal to `/people/cba321` and a required query parameter of `fields=full`.

Any values not specified in this manner will be randomly generated based on the parameter's schema.

### Controlling data generation from schemas

When importing a response with a schema but no examples, WireMock Cloud will randomly generate an example
that conforms to the schema.

For each schema attribute an attempt will be made to determine the data type, using the
`format` if present, but if not making a guess based on the field name. For instance,
a `string` attribute named `date_of_birth` will result in the generation of an ISO8601 local
date within the past 99 years e.g. `1971-08-02`.

However, you can override this behaviour and specify which data generation strategy should be used.
WireMock Cloud uses [Faker](https://github.com/DiUS/java-faker) to generate example data, and
you can specify the specific faker to use by adding an `x-faker` attribute to your schema element e.g.

```yaml theme={null}
schema:
  type: string
  x-faker: name.first_name
```

This can be used both in parameter declarations and response body schemas.

All of the fakers [listed here](https://github.com/DiUS/java-faker/tree/master/src/main/resources/en)
can be used, plus there are some additional rules supplied by WireMock Cloud. The following lists all of the most commonly used, plus all supplied by WireMock Cloud:

* `name.name`
* `name.first_name`
* `name.last_name`
* `name.name_with_middle`
* `name.title`
* `name.prefix`
* `name.suffix`
* `name.username`
* `id.alphanumeric_id`
* `id.uuid`
* `date_and_time.birthday`
* `date_and_time.past_date_time`
* `date_and_time.future_date_time`
* `uri.url`
* `lorem.word`
* `lorem.sentence`
* `lorem.paragraph`
* `currency.code`
* `address.street_address`
* `address.secondary_address`
* `address.city_name`
* `address.state`
* `address.postcode`
* `country.name`
* `country.code2`
* `country.code3`
* `phone_number.phone_number`
* `avatar.image`

<Note>Only required query parameters will be included in the stubs' request criteria. Non-required query parameters will be excluded, meaning that any or no value will be accepted.</Note>