Springdoc と OpenApi が multipart/form-data およびファイル アップロード インターフェイスを記述する方法
まず、Swagger の公式ドキュメントにアクセスします。
https://swagger.io/specation/#schema
現在、私が使用している springdoc のバージョンは 1.69 です
。
multipartコンテンツに関する特別な考慮事項
multipart/form-dataリクエストボディをオペレーションに転送するときにとして使用するのが一般的ですContent-Type。2.0 とは対照的に、コンテンツschemaを使用する場合は、操作への入力パラメータを定義することが必須ですmultipart。これにより、複雑な構造と複数のファイルのアップロードのメカニズムがサポートされます。タイプを渡すとき
multipart、転送されるコンテンツのセクションを区切るために境界を使用できます (MAY)。したがって、 に対して次のデフォルトがContent-Type定義されていますmultipart。
- プロパティがプリミティブまたはプリミティブ値の配列である場合、デフォルトの Content-Type は次のとおりです。
text/plain- プロパティが複雑な場合、または複雑な値の配列の場合、デフォルトの Content-Type は次のとおりです。
application/json- プロパティが
type: stringwithformat: binaryorformat: base64(別名ファイル オブジェクト) の場合、デフォルトの Content-Type は次のとおりです。application/octet-stream
翻訳は次のとおりです。
マルチパートコンテンツに関する特別な考慮事項
リクエストボディをアクションに転送するときは、Content-Type として multipart/form-data を使用するのが一般的です。2.0 とは異なり、マルチパート コンテンツを使用する場合、操作の入力パラメータを定義するためにモードが必須です。これは、複雑な構造と、複数のファイルのアップロードをサポートするメカニズムをサポートします。
マルチパート タイプを渡す場合、境界を使用して、渡されるコンテンツの部分を区切ることができます。したがって、次のデフォルトのコンテンツ タイプがマルチパートに対して定義されます。
- プロパティがプリミティブまたはプリミティブ値の配列の場合、デフォルトの Content-Type は text/plain です。
- プロパティが複雑な場合、または複雑な値の配列の場合、デフォルトの Content-Type は application/json です。
- 属性が type: string、format: binary、または format:base64 (別名ファイル オブジェクト) の場合、デフォルトの Content-Type は application/octet-stream です。
例 例:
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
id:
type: string
format: uuid
address:
# default Content-Type for objects is `application/json`
type: object
properties: {
}
profileImage:
# default Content-Type for string/binary is `application/octet-stream`
type: string
format: binary
children:
# default Content-Type for arrays is based on the `inner` type (text/plain here)
type: array
items:
type: string
addresses:
# default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
type: array
items:
type: '#/components/schemas/Address'
上記の手順に従って、springboot に springdoc 関連のインターフェイス コードを記述します
(CommonResult を String に変更できます)。
@Operation(summary = "上传文件")
@PostMapping("/files/upload")
@RequestBody(content = {
@Content(
mediaType = "multipart/form-data",
schema = @Schema(type = "object"),
schemaProperties = {
@SchemaProperty(
name = "multipartFile",
schema = @Schema(type = "string",format = "binary")
),
@SchemaProperty(
name = "info",
schema = @Schema(type = "object")
)}
)})
public CommonResult<String> upload(MultipartFile multipartFile,
String info){
return CommonResult.success(multipartFile.toString() + info);
}
http://localhost:8888/v3/api-docs中:
{
"/files/upload": {
"post": {
"tags": [
"文件管理"
],
"summary": "上传文件",
"operationId": "upload",
"requestBody": {
"content": {
"application/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"info": {
"type": "object"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/CommonResultString"
}
}
}
}
}
}
}
}
swagger-ui中:
リクエストとレスポンスが送信されました:
成功！
まとめ：公式文書は注意深く読む必要がある