Use cases
The following shows the OpenAPI file, explanations on the API call validation, and valid/invalid API examples for each use case.
-
API server definition, single server
OpenAPI file
openapi: 3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: string
Explanations:
In this example, FortiWeb validates the API call from the following fields:
- The API call is based on host/url:
http://petstore.swagger.io/v1. - The API call path is
/pets, so the full host/url ishttp://petstore.swagger.io/v1/pets. - The API call method is "GET".
- The parameter "limit" is not required, and it must be integer type.
- The "query" means the parameter must be carried in URL parameter after "?".
Valid API request example:
curl http://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"
Invalid API request example:
curl http://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json"
OpenAPI file
openapi: 3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
- url: 'http://petstore2.com/v1'
- url: 'http://petstore3.com/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: string
Explanations:
In this example, multiple server URLs are defined:
- url: 'http://petstore.swagger.io/v1'
- url: 'http://petstore2.com/v1'
- url: 'http://petstore3.com/v1'
It means the three URLs can all match the request host/URL. In another word, http://petstore.swagger.io/v1/pets, http://petstore2.com/v1/pets, and http://petstore3.com/v1/pets all match the method path.
Valid API request examples:
curl http://petstore2.com/v1/pets?limit=123 -H "Accept: application/json"
curl http://petstore3.com/v1/pets?limit=456 -H "Accept: application/json"
Invalid API request examples:
curl http://petstore2.com/v1/pets?limit=abc -H "Accept: application/json"
OpenAPI file:
openapi: 3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets/{petId}:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: petId
in: path
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: string
Explanations:
The "path" indicates the location of the API. The server URL and path must be combined to obtain the full domain/URL of an API call.
In this example, the definition of the "path" is a template /pets/{petId}. petId is a parameter and it is an integer, which is carried n the URL path.
The request domain/URL below can match the API paths:
http://petstore.swagger.io/v1/pets/123
Valid API request example:
curl http://petstore.swagger.io/v1/pets/123 -H "Accept: application/json"
Invalid API request example:
curl http://petstore.swagger.io/v1/pets/abc -H "Accept: application/json"
The parameter validation involves complex serialized rules and attributes settings, and the following examples show how our parameter validation works.
- The location of the parameter
The location of the parameter is described in "in" attribute. According to OpenAPI Specification, 4 locations are supported, query, header, path, and cookie. See API server definition, single server for how to use parameter in "query" location, and API path validation for "path" location. The following example shows how to use parameter in "header" location.
OpenAPI fileopenapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: header
description: How many items to return at one time (max 100)
required: true
schema:
type: integer
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: string
Explanations:
In this example, the parameter "limit" is carried by HTTP header. The type is integer.
Valid API request example:
curl http://petstore.swagger.io/v1/pets/ -H "Accept: application/json" -H "limit: 123"Invalid API request examples:
curl http://petstore.swagger.io/v1/pets/ -H "Accept: application/json" -H "limit: abc"curl http://petstore.swagger.io/v1/pets/?limit=123 -H "Accept: application/json"curl http://petstore.swagger.io/v1/pets/ -H "Accept: application/json" - The data type of the parameter
Besides "integer" and "string", FortiWeb also supports other data types: number and boolean. The following example shows the type boolean.
OpenAPI file:openapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: true
schema:
type: boolean
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type: string
Explanations:
The data type is boolean, the value must be either true or false.
Valid API request example:
curl http://petstore.swagger.io/v1/pets?limit=true -H "Accept: application/json"Invalid API request examples:
curl http://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json" - The HTTP methods
FortiWeb supports HTTP methods, GET, POST, DELETE, and PUT.
OpenAPI file:openapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
post:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: true
schema:
type: boolean
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type:string
Explanations:
In this example, the HTTP method POST is used.
Valid API request example:
curl -X POST http://petstore.swagger.io/v1/pets?limit=false -H "Accept: application/json"Invalid API request example:
curl -X POST http://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json" - Parameter type: array
FortiWeb also supports some complex data types, such as "array" and "object".
The "array" type can be a list of items described by simple types, such as a list of integers or strings.
OpenAPI file:openapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: true
schema:
type: array
items:
type:integer
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type:string
Explanations:
In this example, parameter type "array" is used. Parameters of the same name with be added in an array.
Valid API request example:
curl http://petstore.swagger.io/v1/pets?limit=1&imit=2 -H "Accept: application/json"Invalid API request example:
curl http://petstore.swagger.io/v1/pets?limit=1&imit=abc -H "Accept: application/json"Here is an example when the object type is an aggregation of multiple simple type items.
OpenAPI file:
openapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
explode:false
description: How many items to return at one time (max 100)
required: true
schema:
type: object
required:
- param 1
- param 2
properties:
para1:
type:integer
para2:
type:integer
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type:string
Explanations:
In "object" type, 2 items are declared, param 1 and param2, which are both integers.
Valid API request example:
curl http://petstore.swagger.io/v1/pets?limit=param1,1,param2,1 -H "Accept:application/json"Invalid API request example:
curl http://petstore.swagger.io/v1/pets?limit=param1,1,param2,abc -H "Accept: application/json" - Reference of the schema
Sometimes, the schema of a parameter is long and inconvenient to be written under the parameter declaration. FortiWeb supports schema reference.
OpenAPI file:openapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: true
schema:
$ref: '#/components/schemas/ref'
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type:string
components:
schemas:
ref:
type: integer
Explanations:
In this example, the schema of the parameter is not directly added to the context of the parameter declaration; instead, it declares a reference: $ref: '#/components/schemas/ref'.
Then when parsed, the schema of the parameter will be obtained from components > schema > ref.Valid API request example:
curl http://petstore.swagger.io/v1/pets?limit=123 -H "Accept: application/json"Invalid API request example:
curl http://petstore.swagger.io/v1/pets?limit=abc -H "Accept: application/json" - The request body
The following example shows when you directly submit JSON data in POST body.
OpenAPI file:openapi:3.0.0
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: 'http://petstore.swagger.io/v1'
paths:
/pets:
post:
summary: List all pets
requestBody:
content:
- application/json:
schema:{$ref: '#/components/schemas/pet'}
responses:
'200':
description: A paged array of pets
content:
application/json:
schema:
type:string
components:
schemas:
pet:
required :
- id
- name
properties :
id :
type: integer
name :
type: string
Explanations:
If you post the data
{ "id":1,"name":"test"}directly to the HTTP body, FortiWeb will validate the body directly with the schema in the OpenAPI file.Valid API request example:
curl -X POST http://petstore.swagger.io/v1/pets -H "Accept: application/json" -H "Content-type: application/json" -d '{ "id":1,"name":"test"}'Invalid API request example:
curl -X POST http://petstore.swagger.io/v1/pets -H "Accept: application/json" -H "Content-type: application/json" -d '{ "id":"abc","name":"test"}'