Swagger Import

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

The following sections describe the various approaches available.

Importing manually via the UI

Click the Import button on the stubs toolbar () to open the import dialog box:

Stub toolbar

Then paste your YAML or JSON Swagger definition into the text editor, pick your duplicate policy and hit Import.

Officially the import feature supports version 3.x of Swagger/OAS, although in practice it will import most version 2.x definitions without issue.

Automating imports via the API

You can automate the import process by posting the Swagger definition to your mock API’s admin API.

For instance, assuming you’ve created a mock API with a domain name of my-swagger-api. You can import a new definition by making the following call:

POST http://my-swagger-api.mocklab.io/__admin/imports/open-api-spec

{
  "spec": "<your JSON or YAML Swagger definition>",
  "duplicatePolicy": "ALWAYS_OVERWRITE"
}

The possible values for duplicatePolicy are ALWAYS_OVERWRITE and ALWAYS_CREATE_NEW.

Duplicate policy

If you’re working with a Swagger definition that’s changing on a regular basis, you’ll probably want to re-import it repeatedly.

This means it’s necessary to decide what to do when a stub is newly generated for an url/operation/content type combination for which a stub already exists from a previous import.

Most of the time, for the sake of keeping the mock API correct you’ll want to overwrite the previous stub, so this is the default behaviour.

However, you also have the option of having a new stub created each time. This means if you’ve edited a stub generated from a previous import e.g. to add some specific test data, you won’t lose this and have the opportunity to incorporate it into the newer stub.

Customising the import

Specifying URL path and query parameters

When MockLab 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.

For instance, given the following Open API path element:

/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 requred query parameter of fields=summary. The other will have a URL path equal to /people/cba321 and a requred query parameter of fields=full.

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

Controlling data generation from schemas

When importing a response with a schema but no examples, MockLab 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. MockLab uses 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.

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 can be used, plus there are some additional rules supplied by MockLab. The following lists all of the most commonly used, plus all supplied by MockLab:

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 excluded, meaning that any or no value will be accepted.

Integrating with Swaggerhub

Swaggerhub (Smartbear’s hosted Swagger authoring and collaboration tool), supports integration of external tools via webhooks.

MockLab can be configured as a receiver so that stubs are imported on each save or publish of your Swaggerhub project.

To do this, create a new webhook in the Integrations menu () with a payload URL (which you can also copy from the bottom of the import dialog in the Stubs page) like

http://my-swagger-api.mocklab.io/__admin/imports/swaggerhub?apiToken=l1389usdkfh13,

substituting your own domain name and API token:

Swaggerhub webhook dialog

Once you’ve added this, try saving your API then heading back to MockLab and refreshing your stubs.

note

At present Swaggerhub import will be executed with a duplicate policy of ALWAYS_OVERWRITE.