Open
Description
Q&A (please complete the following information)
- OS: macOS
- Browser: chrome
- Version: 77.0.3865.90
- Method of installation: in browser usage
- Swagger-Editor version: https://editor.swagger.io/#
- Swagger/OpenAPI version: OpenAPI 3.0.0
Content & configuration
Example Swagger/OpenAPI definition:
openapi: 3.0.0
info:
title: BackOffice API for German Portal v2
description: API for integrating SEOS with German Portal
contact:
email: tudor.milencovici@sage.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 2.0.0
servers:
- url: https://api.lab.sageerponlineservices.com/services/azureservices
tags:
- name: Customer
description: Customer (aka Account/Kunde) resource kind
- name: Subscription
description: Subscription (aka Leistung) resource kind
- name: Pricing
description: BO pricing resource kind
- name: Pricing Metadata
description: BO pricing query supporting metadata
paths:
/BOCustomers:
get:
tags:
- Customer
description:
queries for Customer resources. Parameters are considered
to be connected by an AND logical operation
operationId: queryCustomers
parameters:
- name: Id
in: query
required: false
style: form
explode: true
schema:
type: string
format: uuid
- name: userEmail
description:
Indicates that desired are Customers having a contact that
matches the Email
in: query
required: false
style: form
explode: true
schema:
type: string
format: email
- name: primaryContactEmail
description:
Indicates that desired are only those Customers having a PRIMARY CONTACT that
matches the Email
in: query
required: false
style: form
explode: true
schema:
type: string
format: email
- name: partnerId
in: query
required: false
style: form
explode: true
schema:
type: string
format: uuid
- name: partnerEmail
in: query
required: false
style: form
explode: true
schema:
type: string
format: email
- name: productId
in: query
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
200:
description: Customer resources matching criteria
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: "#/components/schemas/BOCustomer"
204:
description: no resource found matching parameters
400:
description: bad input parameter
post:
tags:
- Customer
description: |
creates a Customer. There is a logical differentiation between customers based on the existence of payment information...
* Live customers- are customers paying for our services (and have payment information available)
* Trial customers- who are just testing out one of our products for a given time (have no payment information attached)
The method will create the customer, depending on the above type, as appropriate in the applications/data-stores it controls.
operationId: createCustomer
requestBody:
description: Customer resource contents to be added
content:
application/json:
schema:
$ref: "#/components/schemas/BOCustomer"
required: true
responses:
201:
description: item created
content:
application/json:
schema:
$ref: "#/components/schemas/BOCustomer"
400:
description: invalid input, object invalid
409:
description: an existing item already exists
/BOCustomers/{id}:
delete:
tags:
- Customer
description: deletes a customer
operationId: deleteCustomer
parameters:
- name: id
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
responses:
204:
description: deleted
404:
description: item not found
patch:
tags:
- Customer
description:
updates a customer. It is expected that, if the original Customer does not contain any Payment methods (hence a TRIAL customer)
and the body of the request does, the BO will persist the Customer as a LIVE customer in the appropriate applications/datastores
it controls
operationId: updateCustomer
parameters:
- name: id
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
requestBody:
description: Customer item contents to be amended
content:
application/json:
schema:
$ref: "#/components/schemas/BOCustomer"
required: true
responses:
204:
description: item updated
400:
description: invalid input, object invalid
404:
description: item not found
/BOSubscription:
description: The Subscription resource kind
get:
tags:
- Subscription
description:
Retrieve a Subscription resource list based on the query
criteria passed in the query portion of the URL. Parameters are considered
to be connected by an AND logical operation
operationId: querySubscription
parameters:
- name: Id
in: query
description: The BackOffice Id of a Subscription
required: false
style: form
explode: true
schema:
type: string
format: uuid
- name: customerId
in: query
required: false
style: form
explode: true
schema:
type: string
format: uuid
- name: customerPrimaryContactEmail
in: query
required: false
style: form
explode: true
schema:
type: string
format: email
- name: partnerId
in: query
required: false
style: form
explode: true
schema:
type: string
format: uuid
- name: partnerEmail
in: query
required: false
style: form
explode: true
schema:
type: string
format: email
- name: productId
in: query
required: false
style: form
explode: true
schema:
type: string
format: uuid
responses:
200:
description: Subscription resources matching criteria
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/BOSubscription"
204:
description: no resource found matching parameters
400:
description: bad input parameter
post:
tags:
- Subscription
description: creates a Subscription
operationId: createSubscription
requestBody:
description: Subscription item contents to be added
content:
application/json:
schema:
$ref: "#/components/schemas/BOSubscription"
required: true
responses:
201:
description: Subscription created
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/BOSubscription"
400:
description: invalid input, object invalid
409:
description: an existing item already exists
/BOSubscription/{id}:
delete:
tags:
- Subscription
description: cancels a Subscription
operationId: cancelSubscription
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
204:
description: deleted
404:
description: item not found
patch:
tags:
- Subscription
description: updates a subscription
operationId: updateSubscription
parameters:
- name: id
in: path
required: true
style: simple
explode: false
schema:
type: string
format: uuid
requestBody:
description: Subscription item contents to be amended
content:
application/json:
schema:
$ref: "#/components/schemas/BOSubscription"
required: true
responses:
200:
description: Subscription updated
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/BOSubscription"
204:
description: item updated with no additional content
400:
description: invalid input, object invalid
404:
description: item not found
/BOPrice:
post:
tags:
- Pricing
description:
Obtain a Subscription price based for a given product on the body of the request
operationId: queryPrice
requestBody:
description: Subscription item contents to be amended
content:
application/json:
schema:
properties:
ProductId:
type: string
description: product Id as defined in the BackOffice
nullable: false
CustomerId:
type: string
description: BO CustomerId
nullable: false
Campaign:
$ref: "#/components/schemas/XCampaignAction"
nullable: true
Configuration:
description:
JSON encoded set of name-value pairs as associated with the
product definition. It is logically intended that all the
configuration variables impending on the price resolution be
either directly filled or have default values
type: array
nullable: true
items:
type: object
properties:
Name:
type: string
nullable: false
description:
The name of the query parameter
Value:
type: string
description:
The value of the query parameter. It is assumed that the method knows the
actual type of the parameter (possibly from a template) and performs the
appropriate type conversion for further processing.
nullable: true
required: true
responses:
200:
description: Subscription price successfully determined
content:
application/json:
schema:
type: number
format: decimal
400:
description:
invalid input, object invalid - a single price could not be determined
from provided data. The content will contain a series of elements that
indicate the data needed and the attributes of that data (see below)
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PriceQueryParameter"
404:
description: Product/Customer/Campaign not found
content:
application/json:
schema:
type: array
items:
type: object
description:
Name/value pairs that are incorrect
properties:
Name:
type: number
enum:
- Campaign
- Customer
- Product
Value:
type: string
nullable: true
/BOPrice/QueryTemplates:
post:
tags:
- Pricing Metadata
description:
Persist a query template for a given product
operationId: persistQueryPriceTemplate
parameters:
- name: productId
in: query
description: The BackOffice Id of a product (matchcode=== XLeistung.matchcode)
required: true
style: form
explode: true
schema:
type: string
format: uuid
requestBody:
description: Subscription item contents to be amended
required: true
content:
application/json:
schema:
properties:
ProductId:
type: string
description: product Id as defined in the BackOffice
nullable: false
Template:
type: array
description: array of parameters applicable for the pricing query of the product
nullable: false
items:
$ref: "#/components/schemas/PriceQueryParameter"
responses:
200:
description: Template has been persisted
/BOPrice/QueryTemplates/{productId}:
get:
tags:
- Pricing Metadata
description:
Retrieve a pricing query template for a specific product. The template describes in a generic
manner what the parameters (with metadata) are applicable for the indicated product
operationId: queryPriceTemplate
parameters:
- name: productId
in: path
description: The BackOffice Id of a product (matchcode=== XLeistung.matchcode)
required: true
schema:
type: string
format: uuid
responses:
200:
description: Subscription resources matching criteria
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/PriceQueryParameter"
400:
description: bad input parameter
404:
description: no template was found for the parameter productId indicated
delete:
tags:
- Pricing Metadata
description: deletes a template
operationId: deletePriceTemplate
parameters:
- name: productId
in: path
required: true
schema:
type: string
format: uuid
responses:
204:
description: deleted
404:
description: item not found
components:
schemas:
BOCustomer:
type: object
description: Portal Customer object
properties:
Id:
description: primary identifier for the Customer (XCustomer.kundennummer)
type: string
Address:
$ref: "#/components/schemas/XAdresse"
BankingInfo:
description: BO customer information pertaining to his/her bank
nullable: true
$ref: "#/components/schemas/XBankverbindung"
CreditCardInfo:
description: BO customer information pertaining to a Credit card
nullable: true
$ref: "#/components/schemas/XKreditkarte"
CRMId:
description:
a CRM relevant field - it is ASSUMED this is the CRMId that needs to be used in SEOS. It should be also a unique BO Identifier
For the moment, should correspond to XKunde.cRMSystemField
type: string
IsLocked:
description: indicates that the customer is locked in the BackOffice
type: boolean
Name1:
description: Corresponds to XCustomer.name1Field
type: string
Name2:
description: Corresponds to XCustomer.name2Field
type: string
PartnerInfo:
description:
Information on the business partner. NOTE!!! the businesspartnerField is found within XLeistung
whereas SEOS requires this at the Customer level (SEOS is dumb since different sites may have different PartnerIds!)
type: array
items:
$ref: "#/components/schemas/XPerson"
PaymentKind:
description: should indicate the nature of the payment method customer prefers. NOTE!!! please verfiy this!!!
type: integer
nullable: true
PrimaryContact:
description: Infos for the primary contact of this customer
$ref: "#/components/schemas/XPerson"
Receipts:
description:
Array of receipts as maintained in the BackOffice. Corresponds to XKunde.belegeField.
type: array
items:
$ref: "#/components/schemas/XBeleg"
Settlements:
description:
Array of settlements as maintained in the BackOffice. Corresponds to XKunde.abrechnungenField.
type: array
items:
$ref: "#/components/schemas/XAbrechnung"
Status:
description:
Most likely a customer status. NOTE!!! determine the information here and how it shold
be handled
$ref: "#/components/schemas/XStatus"
Subscriptions:
type: array
items:
$ref: "#/components/schemas/BOSubscription"
Users:
description:
Information on the users of the system. Note!!! as of now, could not discover such information from the BO interfaces
type: array
items:
$ref: "#/components/schemas/XPerson"
BOSubscription:
type: object
properties:
Id:
description:
BO Primary key. Corresponds to XLeistung.leistungsIDField
type: integer
BusinesspartnerId:
description:
BO Primary key. Corresponds to XLeistung.businesspartnerField
type: integer
nullable: true
CustomerId:
type: string
DateCreated:
type: string
format: date-time
EndDate:
type: string
format: date-time
Matchcode:
description:
Contains the identifier for the subscribed product in the BackOffice
type: string
PaidUntilDate:
type: string
format: date-time
Price:
type: number
format: decimal
Quantity:
type: number
format: decimal
ReferenceInfo:
type: string
StartDate:
type: string
format: date-time
PriceParameterTypes:
type: number
enum:
- string
- number
- integer
- boolean
PriceQueryParameter:
type: object
description:
contains metadata describing a query parameters for the pricing resource
properties:
Name:
type: string
DisplayName:
type: string
CurrentValue:
type: string
description:
contains the current value passed to the request. It is in the most generic form
and needs to be converted to its type as defined within the Template object below
nullable: true
Template:
type: object
properties:
Type:
$ref: "#/components/schemas/PriceParameterTypes"
Format:
type: string
description: |
Contains the appropriate format for the Type object above. For example...
* date-time
* email
* decimal
* float
DefaultValue:
type: string
description:
provides the default value in form of a string (the most generic value type). This
must be converted to the appropriate type as specified in the Type property
ValuesAreEnums:
type: boolean
description:
indicates whether the ValueRange contains
discrete an enum or not
ValueRange:
type: array
nullable: true
description:
contains either the values of an enum (ValuesAreEnums==true) or a value range
in which case the lower bound is first and the upper bound last.
items:
type: object
properties:
AllowableValue:
type: string
XAbrechnung:
type: object
properties:
vorgangIDField:
type: integer
abgerechnetVonField:
type: string
format: date-time
abrechnungstypField:
type: string
format: byte
anzahlField:
type: number
format: decimal
leistungField:
$ref: "#/components/schemas/XLeistung"
preisField:
type: number
format: decimal
nullable: true
lieferdatumField:
type: string
format: date-time
zusatzinfoField:
type: string
abgerechnetBisField:
type: string
format: date-time
XAdresse:
type: object
properties:
AdresseIdField:
type: string
AdresseField:
type: string
LandBezeichnungField:
type: string
OrtField:
type: string
PlzField:
type: string
XBankverbindung:
type: object
properties:
bankleitzahlField:
type: string
kontoField:
type: string
kontoinhaberField:
type: string
kreditinstitutField:
type: string
iBANField:
type: string
bICField:
type: string
XBeleg:
type: object
properties:
BelegNummer:
type: string
BelegDetails:
type: array
items:
type: string
format: binary
BelegdatumField:
type: string
format: date-time
BelegJahrField:
type: integer
format: int32
FlagKontingenteField:
type: boolean
Name1Field:
type: string
Name2Field:
type: string
VorgangIDField:
type: number
format: long
XCampaignAction:
type: object
properties:
campaignNameField:
type: string
campaignCodeField:
type: string
campaignActionNameField:
type: string
campaignActionCodeField:
type: string
createDateField:
type: string
format: date-time
XKontingent:
type: object
properties:
Matchcode:
type: string
GueltigBisField:
type: string
format: date-time
AnzahlField:
type: number
format: int
XKunde:
type: object
description: BackOffice customer (Kunde) object. A subset of this is visible through the (portal) Customer object
properties:
BelegeField:
type: array
items:
$ref: "#/components/schemas/XBeleg"
oPsField:
$ref: "#/components/schemas/XOP"
kontingenteField:
type: array
items:
$ref: "#/components/schemas/XKontingent"
sperredetailsField:
$ref: "#/components/schemas/XSperre"
name1Field:
type: string
name2Field:
type: string
adresseField:
$ref: "#/components/schemas/XAdresse"
sperreBisField:
type: string
format: date-time
ansprechpartnerField:
$ref: "#/components/schemas/XPerson"
abrechnungenField:
type: array
items:
$ref: "#/components/schemas/XAbrechnung"
statusField:
$ref: "#/components/schemas/XStatus"
cRMSystemField:
type: integer
kundennummerField:
type: integer
nullable: true
telefaxField:
type: string
telefonField:
type: string
bankverbindungField:
$ref: "#/components/schemas/XBankverbindung"
zahlungsartField:
type: integer
nullable: true
kreditkarteField:
$ref: "#/components/schemas/XKreditkarte"
leistungsumfangField:
type: array
items:
$ref: "#/components/schemas/XLeistung"
alternativAdressenField:
type: array
items:
$ref: "#/components/schemas/XAdresse"
flagDublettenpruefungField:
type: boolean
nullable: true
eBillingEmailField:
type: string
format: email
eBillingEmailNeuField:
type: string
format: email
flagKeinEBillingField:
type: boolean
nullable: true
flagGepruefterAccoutNotwendigField:
type: boolean
servicenehmerField:
type: string
XKreditkarte:
type: object
properties:
gesellschaftField:
type: string
inhaberField:
type: string
nummerField:
type: string
nummerZusatzField:
type: string
gueltigBisField:
type: string
format: date-time
XLeistung:
type: object
properties:
matchcodeField:
type: string
istKontingentField:
type: boolean
dateCreatedField:
type: string
format: date-time
leistungsIDField:
type: integer
businesspartnerField:
type: integer
nullable: true
referenzField:
type: string
mengeField:
type: number
format: decimal
preisField:
type: number
format: decimal
startdatumField:
type: string
format: date-time
enddatumField:
type: string
format: date-time
abgerechnetBisField:
type: string
format: date-time
XOP:
type: object
properties:
faelligkeitField:
type: string
format: date-time
oPNummerField:
type: string
oPDatumField:
type: string
format: date-time
betragField:
type: number
belegField:
$ref: "#/components/schemas/XBeleg"
XPerson:
type: object
properties:
anredeField:
type: string
nameField:
type: string
vornameField:
type: string
telefonField:
type: string
telefaxField:
type: string
emailAdresseField:
type: string
format: email
personIdField:
type: integer
campaignActionsField:
$ref: "#/components/schemas/XCampaignAction"
XSperre:
type: object
properties:
IdField:
type: number
format: int
GueltigVonField:
type: string
format: date-time
GueltigBisField:
type: string
format: date-time
FehlerTypen:
type: number
enum:
- Information
- Warning
- Error
XStatus:
type: object
properties:
fehlertypField:
$ref: "#/components/schemas/FehlerTypen"
fehlernummerField:
type: integer
fehlerbeschreibungField:
type: string
systemmeldungField:
type: stringSwagger-Editor configuration options:
SwaggerEditor({
// your config options here
})?yourQueryStringConfig
Describe the bug you're encountering
To reproduce...
Steps to reproduce the behavior:
- load attached definition (it has warnings but no errors)
- Generate HTML2 client
- nothing happens
Expected behavior
expected the html documentation to be generated