4.7.3. 创建 MicroProfile OpenAPI 应用
创建返回 OpenAPI v3 文档的应用。
先决条件
- Maven 项目已配置为创建 MicroProfile OpenAPI 应用。
流程
创建用于存储类文件的目录:
$ mkdir -p APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/
APPLICATION_ROOT 是含有应用的
pom.xml
配置文件的目录。进入新目录:
$ cd APPLICATION_ROOT/src/main/java/com/example/microprofile/openapi/
必须在此目录中创建下列步骤中的所有类文件。
使用以下内容创建类文件
InventoryApplication.java
:package com.example.microprofile.openapi; import javax.ws.rs.ApplicationPath; import javax.ws.rs.core.Application; @ApplicationPath("/inventory") public class InventoryApplication extends Application { }
此类充当应用的 REST 端点。
创建包含以下内容的类文件
Fruit.java
:package com.example.microprofile.openapi; public class Fruit { private final String name; private final String description; public Fruit(String name, String description) { this.name = name; this.description = description; } public String getName() { return this.name; } public String getDescription() { return this.description; } }
创建包含以下内容的类文件
FruitResource.java
:package com.example.microprofile.openapi; import java.util.Collections; import java.util.LinkedHashMap; import java.util.Set; import javax.ws.rs.Consumes; import javax.ws.rs.DELETE; import javax.ws.rs.GET; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.Produces; import javax.ws.rs.core.MediaType; @Path("/fruit") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) public class FruitResource { private final Set<Fruit> fruits = Collections.newSetFromMap(Collections.synchronizedMap(new LinkedHashMap<>())); public FruitResource() { this.fruits.add(new Fruit("Apple", "Winter fruit")); this.fruits.add(new Fruit("Pineapple", "Tropical fruit")); } @GET public Set<Fruit> all() { return this.fruits; } @POST public Set<Fruit> add(Fruit fruit) { this.fruits.add(fruit); return this.fruits; } @DELETE public Set<Fruit> remove(Fruit fruit) { this.fruits.removeIf(existingFruit -> existingFruit.getName().contentEquals(fruit.getName())); return this.fruits; } }
进入应用程序的根目录:
$ cd APPLICATION_ROOT
使用以下 Maven 命令构建和部署应用程序:
$ mvn wildfly:deploy
测试应用。
使用
curl
访问示例应用程序的 OpenAPI 文档:$ curl http://localhost:8080/openapi
返回以下输出:
openapi: 3.0.1 info: title: Archetype Created Web Application version: "1.0" servers: - url: /microprofile-openapi paths: /inventory/fruit: get: responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Fruit' post: requestBody: content: application/json: schema: $ref: '#/components/schemas/Fruit' responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Fruit' delete: requestBody: content: application/json: schema: $ref: '#/components/schemas/Fruit' responses: "200": description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Fruit' components: schemas: Fruit: type: object properties: description: type: string name: type: string
其它资源
- 如需 MicroProfile SmallRye OpenAPI 中定义的注释列表,请参阅 MicroProfile OpenAPI 注释。