当 API 中未发送必填字段值时，如何在 swagger 中自定义错误消息？
Posted
技术标签:
【中文标题】当 API 中未发送必填字段值时，如何在 swagger 中自定义错误消息？【英文标题】：How to customize error message in swagger when mandatory fields value are not sent in API? 【发布时间】：2019-03-02 05:12:41 【问题描述】：下面是我的 api.yml：
openapi: 3.0.0
info:
title: 'AutoDelievery API'
description: 'AutoDelievery API Documentation'
termsOfService: 'https://www.yopmail.com'
contact:
name: yopmail
url: 'http://www.yopmail.com'
email: contactus@yopmail.com
license:
name: yopmail
url: 'http://www.yopmail.com/licenses/yopmail-AutoDelievery-Licence.html'
version: 1.0.0-oas3
servers:
-
url: 'http://localhost:5055/'
tags:
-
name: AutoDelievery
description: 'AutoDelievery product related APIs'
externalDocs:
description: 'Documentation:'
url: 'http://localhost:5055/external/doc'
paths:
/autoDelievery:
post:
tags: [autoDelievery]
summary: 'Creates a new autoDelievery record'
operationId: insertSubscription
requestBody: description: 'autoDelievery request body', content: application/json: schema: $ref: '#/components/schemas/AutoDelievery'
responses: '200': description: 'successful operation', content: application/json: schema: $ref: '#/components/schemas/AutoDelievery', '400': description: 'Bad Request', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError', '500': description: 'Server Error', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError'
'/autoDelievery/autoDelieveryID':
get:
tags: [AutoDelievery]
summary: 'AutoDelievery as per ID'
description: 'Fetches the AutoDelievery for the provided Id'
operationId: getAutoDelieveryById
parameters: [in: path, name: autoDelieveryID, required: true, schema: type: string]
responses: '200': description: 'successful operation', content: application/json: schema: $ref: '#/components/schemas/AutoDelievery', '400': description: 'Server Error', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError'
delete:
tags: [autoDelievery]
summary: 'Delete AutoDelievery as per ID'
description: 'Finds the autoDelievery for the provided Id and deletes the same'
operationId: deleteAutoDelieveryById
parameters: [in: path, name: autoDelieveryID, required: true, schema: type: string]
responses: '200': description: 'successful operation', content: application/json: schema: $ref: '#/components/schemas/AutoDelievery', '400': description: 'Server Error', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError'
'/autoDelievery/autoDelieveryID/payment':
put:
tags: [AutoDelievery]
summary: 'Updates autoDelievery payment details'
parameters: [in: path, name: autoDelieveryID, description: 'AutoDelievery Id of which payment details are to be updated', required: true, schema: type: string]
operationId: updatePayment
requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentMethod'
responses: '200': description: 'successful operation', content: application/json: schema: $ref: '#/components/schemas/AutoDelievery', '400': description: 'Bad Request', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError', '500': description: 'Server Error', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError'
'/autoDelievery/autoDelieveryId/frequency':
put:
tags: [AutoDelievery]
summary: 'Updates AutoDelievery frequency, quantity and end data.'
parameters: [in: path, name: autoDelieveryId, description: 'AutoDelievery Id of which frequency is to be updated', required: true, schema: type: string]
operationId: updateFrequency
requestBody: content: application/json: schema: $ref: '#/components/schemas/Frequency'
responses: '200': description: 'successful operation', content: application/json: schema: $ref: '#/components/schemas/AutoDelievery', '400': description: 'Bad Request', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError', '500': description: 'Server Error', content: application/json: schema: $ref: '#/components/schemas/AutoDelieveryError'
components:
schemas:
SubscriptionList:
type: object
properties: count: type: integer, result: type: array, items: $ref: '#/components/schemas/AutoDelievery', page: type: integer
DataEntity:
type: object
properties: id: type: string, lastModifiedDate: type: string, createdDate: type: string
AutoDelievery:
allOf: [$ref: '#/components/schemas/DataEntity', type: object, required: [userId, clientId, quantity, frequency, payment, product, shippingAddress], properties: userId: type: string, clientId: type: string, parentSubscriptionId: type: string, product: $ref: '#/components/schemas/Product', quantity: type: integer, minimum: 1, frequency: type: number, minimum: 1, payment: $ref: '#/components/schemas/PaymentMethod', paymentMethodId: type: string, shippingMethodId: type: string, nextOrderDate: type: string, subscriptionStartDate: type: string, subscriptionEndDate: type: string, shippingMethod: type: string, shippingAddress: $ref: '#/components/schemas/Address']
Product:
type: object
required: [productId]
properties: productId: type: string, productDescription: type: string
PaymentMethod:
type: object
required: [billingAddress]
properties: createdDate: type: string, modifiedDate: type: string, paymentType: type: string, billingAddress: $ref: '#/components/schemas/Address'
discriminator: propertyName: paymentType
Frequency:
type: object
required: [frequency, quantity]
properties: frequency: type: number, minimum: 1, subscriptionEndDate: type: string, quantity: type: integer, minimum: 1
Card:
allOf: [$ref: '#/components/schemas/PaymentMethod', type: object, required: [nameOnCard, lastFourDigits, expiryMonth, expiryYear], properties: nameOnCard: type: string, lastFourDigits: type: string, token: type: string, expiryMonth: type: string, minLength: 2, maxLength: 2, expiryYear: type: string, format: year, discriminator: propertyName: paymentType]
PayPal:
allOf: [$ref: '#/components/schemas/PaymentMethod', type: object, required: [accountId], properties: accountId: type: string]
Payment:
type: object
properties: payment: allOf: [$ref: '#/components/schemas/PaymentMethod'], discriminator: propertyName: paymentType
Address:
type: object
required: [firstName, lastName, addressLine1, city, state, postalCode, country]
properties: prefix: type: string, firstName: type: string, middleName: type: string, lastName: type: string, suffix: type: string, title: type: string, companyName: type: string, addressLine1: type: string, addressLine2: type: string, city: type: string, state: type: string, postalCode: type: string, country: type: string, phoneNumber: type: string, mobilePhoneNumber: type: string
Status:
type: object
required: [status]
properties: status: type: string, details: type: string
Shipping:
type: object
properties: shippingMethodId: type: string, shippingMethod: type: string
PaymentAuthorization:
type: object
properties: authId: type: string
CommerceItem:
type: object
required: [subscriptionId, quantity, product]
properties: subscriptionId: type: string, product: $ref: '#/components/schemas/Product', quantity: type: number, minimum: 1, itemUnitPrice: type: number, itemTotalPrice: type: number, itemDiscount: type: number
ErrorResponse:
type: object
required: [errorMessage]
properties: field: type: string, errorMessage: type: string
ErrorResponseList:
type: object
required: [errors]
properties: errors: type: array, items: $ref: '#/components/schemas/ErrorResponse'
NoSubscriptionResponse:
allOf: [$ref: '#/components/schemas/ErrorResponseList']
AutoDelieveryError:
allOf: [$ref: '#/components/schemas/ErrorResponseList']
NoOrderResponse:
allOf: [$ref: '#/components/schemas/ErrorResponseList']
我的示例 api 是：
"id": "string",
"lastModifiedDate": "string",
"createdDate": "string",
"userId": null,
"clientId": "string",
"parentSubscriptionId": "string",
"product":
"productId": "string",
"productDescription": "string"
,
"quantity": 0,
"frequency": 0,
"payment":
"createdDate": "string",
"modifiedDate": "string",
"paymentType": "string",
"billingAddress":
"prefix": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"suffix": "string",
"title": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"postalCode": "string",
"country": "string",
"phoneNumber": "string",
"mobilePhoneNumber": "string"
,
"paymentMethodId": "string",
"shippingMethodId": "string",
"nextOrderDate": "string",
"subscriptionStartDate": "string",
"subscriptionEndDate": "string",
`enter code here`"shippingMethod": "string",
"shippingAddress":
"prefix": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"suffix": "string",
"title": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"state": "string",
"postalCode": "string",
"country": "string",
"phoneNumber": "string",
"mobilePhoneNumber": "string"
我收到以下格式的错误响应：
"errors": [
"field": "userId",
"errorMessage": "must not be null"
]
我应该怎么做才能有自定义的错误消息？
【问题讨论】：
你解决了吗？ 【参考方案1】：Swagger 在创建 POJO 时将 @NotNull 注释放在 required 字段上。
Message interpolation 可以通过在类路径中创建ValidationMessages.properties 文件来完成，如下所示：
javax.validation.constraints.NotNull.message=CUSTOMIZED ERROR MESSAGE
它将覆盖来自的默认错误消息
/org/hibernate/validator/ValidationMessages.properties
【讨论】：
以上是关于当 API 中未发送必填字段值时，如何在 swagger 中自定义错误消息？的主要内容，如果未能解决你的问题，请参考以下文章