Sie haben die Möglichkeit, eine Swagger-Dokumentation zu erzeugen.
Die erzeugte Swagger-Dokumentation enthält die Beschreibung der Endpunkte, die von Ihnen angelegt wurden.
Sie enthält auch die Beschreibung der Portal-Endpunkte, die standardmäßig jedes Portal enthält.
Nähere Informationen zu den Portal-Endpunkten finden Sie in Abschnitt Login-API-Endpunkte.
Schritt-für-Schritt
Um eine Swagger-Dokumentation zu erzeugen, gehen Sie wie folgt vor:
-
Starten Sie das Modul "Integration".
-
Klicken Sie auf "API-Endpunkte".
Sie gelangen in die Übersicht der API-Endpunkte Ihres Portals.
-
Markieren Sie die Applikation, für die Sie die Swagger-Dokumentation erstellen möchten.
-
Führen Sie einen Rechtsklick aus.
Ein Kontextmenü wird angezeigt.
Klicken Sie auf "Swagger-Dokumentation erstellen"
Oder
Klicken Sie im Hauptmenü auf "API-Endpunkte" > "Swagger-Dokumentation erstellen".
Oder
Klicken Sie auf {...} in der Symbolleiste.
-
Speichern Sie die Swagger-Dokumentation.
Die Swagger-Dokumentation wird im Format "yaml" abgelegt.
Beispiel - Swagger-Dokumentation
openapi: 3.0.0
info:
title: Intrexx Application API
description: Access Intrexx Applications using our REST-API
version: 1.0.0
servers:
- url: https://localhost:1340
paths:
/api/app/BD1B72A88BBE6915AF4641F3A25E015EE16D41A6/delete-store/{strid}:
delete:
description: Delete data record in store data group
operationId: Delete-data-record-in-store
tags:
- Application Endpoints
parameters:
- description: Primary key - ID automatically generated by Intrexx
in: path
name: strid
required: true
schema:
type: string
- description: The CSRF-Token header.
in: header
name: X-CSRF-Token
required: true
schema:
type: string
responses:
'204':
description: Delete a record (no content).
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/api/app/BD1B72A88BBE6915AF4641F3A25E015EE16D41A6/Get-data-one-store/{strid}:
get:
description: Get all data of one data record in store
operationId: Get-one-data-record-in-store
tags:
- Application Endpoints
parameters:
- description: GUID
in: path
name: strid
required: true
schema:
type: string
responses:
'200':
description: Response object.
content:
application/json:
schema:
$ref: '#/components/schemas/Get-one-data-record-in-storeResponse'
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/api/app/BD1B72A88BBE6915AF4641F3A25E015EE16D41A6/get-stores-in-given-city:
get:
description: Get stores in a given city
operationId: Get-stores-in-given-city
tags:
- Application Endpoints
parameters:
- description: City whre store is located
in: query
name: store-city
required: true
schema:
type: string
- description: The field(s) to order by.
in: query
name: orderby
required: false
schema:
type: string
- description: The limit.
in: query
name: limit
required: false
schema:
type: integer
- description: The offset at which to fetch the next records (paging).
in: query
name: offset
required: false
schema:
type: integer
- description: The number of results.
in: query
name: count
required: false
schema:
type: integer
responses:
'200':
description: Array of object records.
content:
application/json:
schema:
$ref: '#/components/schemas/Get-stores-in-given-cityResponse'
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/api/app/BD1B72A88BBE6915AF4641F3A25E015EE16D41A6/create-store:
post:
description: Create store record
operationId: Create-store-record
tags:
- Application Endpoints
parameters:
- description: The CSRF-Token header.
in: header
name: X-CSRF-Token
required: true
schema:
type: string
requestBody:
description: The record to insert into the datagroup.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Create-store-recordRequest'
responses:
'200':
description: Response object.
content:
application/json:
schema:
$ref: '#/components/schemas/Create-store-recordResponse'
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/api/app/BD1B72A88BBE6915AF4641F3A25E015EE16D41A6/patch-record/{strid}:
patch:
description: Modify store record
operationId: Modify-store-record
tags:
- Application Endpoints
parameters:
- description: GUID
in: path
name: strid
required: true
schema:
type: string
- description: The CSRF-Token header.
in: header
name: X-CSRF-Token
required: true
schema:
type: string
requestBody:
description: The record to insert into the datagroup.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Modify-store-recordRequest'
responses:
'200':
description: Response object.
content:
application/json:
schema:
$ref: '#/components/schemas/Modify-store-recordResponse'
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/api/app/upload:
post:
description: Upload files endpoint.
operationId: uploadRequest
tags:
- Portal endpoints
parameters:
- description: The field GUID of the file field.
in: query
name: fieldGuid
required: true
schema:
type: string
- description: The record-ID of the record the file belongs to.
in: query
name: recId
required: true
schema:
type: string
- description: The name of the file.
in: query
name: fileName
required: true
schema:
type: string
- description: The action mode (optional).
in: query
name: actionMode
required: false
schema:
type: string
- description: The CSRF-Token header.
in: header
name: X-CSRF-Token
required: true
schema:
type: string
requestBody:
description: The file to upload.
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/uploadRequest'
responses:
'200':
description: File uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/uploadResponse'
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/api/app/download:
get:
description: Download files endpoint.
operationId: download
tags:
- Portal endpoints
parameters:
- description: The field GUID of the file field.
in: query
name: fieldGuid
required: true
schema:
type: string
- description: The record-ID of the record the file belongs to.
in: query
name: recId
required: true
schema:
type: string
- description: The ID of the file.
in: query
name: fileId
required: true
schema:
type: string
- description: The disposition HTTP-header to set (optional).
in: query
name: disposition
required: false
schema:
type: string
- description: The CSRF-Token header.
in: header
name: X-CSRF-Token
required: true
schema:
type: string
responses:
'200':
description: File download (HTTP-body).
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/downloadResponse'
'400':
description: Bad Request (client sent something wrong).
'500':
description: Internal server error.
/service/login/login:
post:
summary: Login a user.
description: Login a user.
operationId: login
tags:
- Login
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/credentials'
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/loginResponse'
headers:
Set-Cookie:
schema:
type: string
example: co_SId=DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF; Path=/;
HttpOnly; SameSite=Lax
405:
description: If the method chosen was not POST.
content:
application/json:
schema:
$ref: '#/components/schemas/jsonResponse405'
/service/login/logout:
post:
summary: Logout the current session.
description: Logout the current session.
operationId: logout
tags:
- Login
responses:
200:
description: Successful logout.
content:
application/json:
schema:
$ref: '#/components/schemas/jsonResponse200'
410:
description: If the session was not found on the server.
content:
application/json:
schema:
$ref: '#/components/schemas/jsonResponse410'
405:
description: If the method chosen was not POST.
content:
application/json:
schema:
$ref: '#/components/schemas/jsonResponse405'
/service/login/getSessionInfo:
get:
summary: Get information about the current session.
description: Returns information about the current session.
operationId: getSessionInfo
tags:
- Login
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/getSessionInfoResponse'
/service/login/getAuthenticationTokenTypes:
get:
summary: Get information about login token types.
description: Returns information about login token types.
operationId: getAuthenticationTokenTypes
tags:
- Login
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/getAuthenticationTokenTypesResponse'
/service/login/getLoginDomains:
get:
summary: Get a list of available login domains.
description: Returns a list of available login domains.
operationId: getLoginDomains
tags:
- Login
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/getLoginDomainsResponse'
components:
schemas:
sessionInfo:
type: object
properties:
sessionTimeout:
type: integer
format: int64
minimum: 0
example: 3600000
lastAccessTime:
type: integer
format: int64
example: 1099655520000
anonymous:
type: boolean
cookieMatch:
type: boolean
CSRFToken:
type: string
example: DEADBEEFDEADBEEFDEADBEEFDEADBEEFDEADBEEF
userName:
type: string
example: daisyd
getAuthenticationTokenTypesResponse:
type: object
required:
- authenticationTokenTypes
properties:
authenticationTokenTypes:
type: object
required:
- module
properties:
module:
type: object
required:
- tokenTypes
properties:
tokenTypes:
type: array
items:
type: string
enum:
- userName
- domainName
- password
example:
- userName
- domainName
- password
jsonResponse200:
type: object
required:
- success
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
timestamp:
type: string
format: date-time
example: '2004-11-05T11:52:00Z'
message:
type: string
example: OK
jsonResponse410:
type: object
required:
- success
properties:
success:
type: boolean
example: false
status:
type: integer
example: 410
timestamp:
type: string
format: date-time
example: '2004-11-05T11:52:00Z'
message:
type: string
example: Gone
loginResponse:
type: object
required:
- loginResponse
properties:
loginResponse:
$ref: '#/components/schemas/sessionInfo'
credentials:
type: object
required:
- credentials
properties:
credentials:
type: object
additionalProperties:
type: string
example:
userName: daisyd
domainName: example.org
password: secret
getLoginDomainsResponse:
type: object
required:
- loginDomains
properties:
loginDomains:
type: array
items:
type: string
example:
- example.org
- example.com
Modify-store-recordResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: ''
uploadResponse:
type: object
properties:
downloadUrl:
type: string
description: The URL to download the file again.
Create-store-recordRequest:
type: object
properties:
storecity:
type: string
description: City where store is located
storeid:
type: string
description: Store id
storemanager:
type: string
description: Store manager
storeproduct:
type: string
description: Main product sold in store
Create-store-recordResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: ''
getSessionInfoResponse:
type: object
required:
- sessionInfo
properties:
sessionInfo:
$ref: '#/components/schemas/sessionInfo'
Get-stores-in-given-cityResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: GUID
storecity:
type: string
description: City store is located
storeid:
type: string
description: Store id
storemanager:
type: string
description: Store manager
storeproduct:
type: string
description: Main product sold in store
uploadRequest:
type: string
format: binary
downloadResponse:
type: string
format: binary
AnyValue: {}
jsonResponse405:
type: object
required:
- success
properties:
success:
type: boolean
example: false
status:
type: integer
example: 405
timestamp:
type: string
format: date-time
example: '2004-11-05T11:52:00Z'
message:
type: string
example: Method Not Allowed
Modify-store-recordRequest:
type: object
properties:
storecity:
type: string
description: City where store is located
storeid:
type: string
description: Store id
storemanager:
type: string
description: Store manager
storeproduct:
type: string
description: Main product sold in store
Get-one-data-record-in-storeResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: GUID
storecity:
type: string
description: City whre store is located
storeid:
type: string
description: Store id - created manually
storemanager:
type: string
description: First name and family name of store manager
storeproduct:
type: string
description: Main product sold in store
securitySchemes:
cookieAuth:
type: apiKey
in: cookie
name: co_SId
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- cookieAuth: []
- ApiKeyAuth: []
Senden Sie uns eine E-Mail