Swagger (OpenAPI) 2.0
A Swagger (OpenAPI) 2.0 definition can be converted to or from an FSD file using the fsdgenswagger command-line tool.
fsdgenswagger
fsdgenswagger is a command-line tool that converts Swagger to FSD or FSD to Swagger.
Install fsdgenswagger as documented from its NuGet package.
fsdgenswagger accepts an FSD file or a Swagger file as input and generates an FSD file or a Swagger file as output. It supports the standard command-line options as well as the following additional command-line options:
--fsd: Generates an FSD file (instead of a Swagger file).--json: Generates JSON (instead of YAML) when generating a Swagger file.--service-name <name>: Overrides the service name.
Swagger Schema
This section describes the Swagger fields supported by Facility and their equivalent in FSD.
Not every feature in Swagger is supported. Facility API information without a corresponding Swagger field is stored in an extension field (starts with x-).
Facility does not currently support $ref fields that span files.
Facility supports both JSON and YAML formats for a Swagger definition file.
Swagger Object
Defines the service.
| Field Name | FSD Equivalent |
|---|---|
swagger | (always 2.0) |
info | (see Info Object) |
host | [http(url: "...://(host)/...")] on service |
basePath | [http(url: ".../(basePath)")] on service |
schemes | [http(url: "(scheme)://...")] on service |
consumes | (ignored) |
produces | (ignored) |
paths | (see Path Object) |
definitions | (see Schema Object) |
parameters | (see Parameter Object) |
responses | (see Responses Object) |
securityDefinitions | (ignored) |
security | (ignored) |
tags | (ignored) |
externalDocs | (ignored) |
Only one scheme is supported by FSD. https is preferred over http.
Info Object
Defines the service.
| Field Name | FSD Equivalent |
|---|---|
title | service summary |
description | service remarks |
termsOfService | (ignored) |
contact | (ignored) |
license | (ignored) |
version | [info(version: (version))] on service |
x-identifier | service name |
x-codegen | (set by fsdgenfsd --swagger) |
If the service name is not specified by x-identifier or the --serviceName command-line option, a service name is created from the title.
Path Object
Defines one or more methods.
| Field Name | FSD Equivalent |
|---|---|
(path) | [http(path: "(path)")] on method (see Path Item Object) |
Path Item Object
Defines one or more methods.
| Field Name | FSD Equivalent |
|---|---|
$ref | (supports internal references) |
get | [http(method: GET)] on method (see Operation Object) |
put | [http(method: PUT)] on method (see Operation Object) |
post | [http(method: POST)] on method (see Operation Object) |
delete | [http(method: DELETE)] on method (see Operation Object) |
options | [http(method: OPTIONS)] on method (see Operation Object) |
head | [http(method: HEAD)] on method (see Operation Object) |
patch | [http(method: PATCH)] on method (see Operation Object) |
parameters | (see Parameter Object) |
Operation Object
Defines a method.
| Field Name | FSD Equivalent |
|---|---|
tags | (ignored) |
summary | method summary |
description | method remarks |
externalDocs | (ignored) |
operationId | method name |
consumes | (application/json as appropriate) |
produces | (application/json as appropriate) |
parameters | (see Parameter Object) |
responses | (see Responses Object) |
schemes | (ignored) |
deprecated | [obsolete] on method |
security | (ignored) |
If operationId is not specified, a method name is created from the HTTP method and path.
Parameter Object
Defines a request field and its type.
| Field Name | FSD Equivalent |
|---|---|
$ref | (supports internal references) |
in | [http(from: (path|query|header|body))] on field (formData not supported) |
name | query, path, or header name |
description | field summary |
required | (true for path parameter; ignored otherwise) |
schema | (see Schema Object) |
type | field type (see Data Types) |
format | field type (see Data Types) |
allowEmptyValue | (ignored) |
items | array value type (see Data Types) |
collectionFormat | (ignored) |
default | (ignored) |
maximum | (ignored) |
exclusiveMaximum | (ignored) |
minimum | (ignored) |
exclusiveMinimum | (ignored) |
maxLength | (ignored) |
minLength | (ignored) |
pattern | (ignored) |
maxItems | (ignored) |
minItems | (ignored) |
uniqueItems | (ignored) |
enum | enum values |
multipleOf | (ignored) |
x-identifier | field name |
x-obsolete | [obsolete] on field |
If x-identifier is not specified, the field name is set to the name field (or "body" for body fields).
Responses Object
Defines response fields of a method.
| Field Name | FSD Equivalent |
|---|---|
(code) | [http(code: (code))] on the method or the corresponding body field (see Response Object) |
Response Object
Defines response fields of a method.
| Field Name | FSD Equivalent |
|---|---|
$ref | (supports internal references) |
description | body field summary |
schema | response field(s) or body field (see Schema Object) |
headers | (ignored) |
examples | (ignored) |
x-identifier | body field name |
If operationId is not specified, a method name is created from the HTTP method and path.
Schema Object
An items object, header object, or schema object. Defines a DTO, a field, or a field type.
| Field Name | FSD Equivalent |
|---|---|
$ref | (supports internal references) |
description | field summary |
required | (ignored) |
title | (ignored) |
type | field type (see Data Types) |
format | field type (see Data Types) |
items | array value type (see Data Types) |
maxProperties | (ignored) |
minProperties | (ignored) |
default | (ignored) |
maximum | (ignored) |
exclusiveMaximum | (ignored) |
minimum | (ignored) |
exclusiveMinimum | (ignored) |
maxLength | (ignored) |
minLength | (ignored) |
pattern | (ignored) |
maxItems | (ignored) |
minItems | (ignored) |
uniqueItems | (ignored) |
enum | enum values |
multipleOf | (ignored) |
properties | DTO fields |
allOf | (ignored) |
additionalProperties | map value type (see Data Types) |
discriminator | (ignored) |
readOnly | (ignored) |
xml | (ignored) |
externalDocs | (ignored) |
example | (ignored) |
x-identifier | field name |
x-obsolete | [obsolete] on field |
x-remarks | DTO remarks |
If x-identifier is not specified, the field name is set to the name field (or "body" for body fields).
Data Types
The following table describes how each Swagger type and optional format map to an FSD field type.
| Swagger type | Swagger format | FSD Type |
|---|---|---|
boolean | boolean | |
integer | int32 | |
integer | int32 | int32 |
integer | int64 | int64 |
number | double | |
number | float | double |
number | double | double |
number | decimal | decimal |
string | string, enum | |
string | byte | bytes |
string | binary | string |
string | date | string |
string | date-time | string |
string | password | string |
object | DTO, error, result<T>, map<T>, object | |
array | T[] | |
file | (not supported) |