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:
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:
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.