MicroProfile OpenApi дает нам стандартизированный способ описания нашего API JAX-RS с использованием OpenApi 3. Если вы ранее использовали swagger-jaxrs и swagger -annotations , вам это будет очень знакомо, поскольку OpenApi построен на основе Swagger.
5 ноября 2015 года SmartBear совместно с 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal и Restlet объявили о создании Open API Initiative, проекта с открытым исходным кодом под управлением Linux Foundation. В рамках формирования OAI SmartBear пожертвовал спецификацию Swagger для Linux Foundation, что означает, что спецификация OpenAPI семантически идентична спецификации, ранее известной как спецификация Swagger 2.0 — www.openapis.org/faq
Краткая информация
заявка
Во-первых, в своем классе, который расширяет javax.ws.rs.core.Application , добавьте информацию заголовка о вашем API:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
|
@ApplicationPath("/api") @OpenAPIDefinition(info = @Info( title = "Example application", version = "1.0.0", contact = @Contact( name = "Phillip Kruger", ), servers = { @Server(url = "/example",description = "localhost") } ) public class ApplicationConfig extends Application { } |
(см. полный пример здесь )
обслуживание
Затем в вашем сервисе (ах) добавьте аннотации, описывающие ваш сервис:
-
@Tag -
@Operation -
@APIResponse - и т.п.
пример:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
@RequestScoped @Path("/config") @Tag(name = "Config Retrieval service", description = "Get the value for a certain config") public class ConfigRetrievalService { @Inject private Config config; @GET @Path("/{key}") @Operation(description = "Get the value for this key") @APIResponses({ @APIResponse(responseCode = "200", description = "Successful, returning the value") }) @Produces(MediaType.TEXT_PLAIN) public Response getConfigValue(@PathParam("key") String key) { String value = config.getValue(key, String.class); log.log(Level.INFO, "{0} = {1}", new Object[]{key, value}); return Response.ok(value).build(); } } |
(см. полный пример здесь и еще один (более полный) пример здесь )
Получение openapi yaml
Теперь, если вы запустите свое приложение, вы можете перейти к /openapi чтобы получить yaml:
|
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
|
openapi: 3.0.0 info: title: Example application contact: name: Phillip Kruger email: [email protected] version: 1.0.0 servers: - url: /example description: localhost tags: - name: Simulate some exeption description: Create some exception - name: Config Retrieval service description: Get the value for a certain config paths: /api/config/{key}: get: tags: - Config Retrieval service description: Get the value for this key operationId: getConfigValue parameters: - name: key in: path required: true style: simple schema: type: string responses: 200: description: Successful, returning the value /api/exception: get: tags: - Simulate some exeption description: Throw an exeption operationId: doSomething responses: 412: description: You made a mistake components: {} |
Добавление Swagger UI
Выше краткий обзор MicroProfile OpenAPI. Об этом подробнее здесь:
Последний пользовательский интерфейс Swagger работает на OpenAPI, и вы можете вручную добавить его в свой проект (см. Этот замечательный пост Хайри Чичек) или использовать эту полезную библиотеку, которая добавит его автоматически:
В вашем pom.xml :
|
1
2
3
4
5
|
<dependency> <groupId>com.github.phillip-kruger.microprofile-extensions</groupId> <artifactId>openapi-ext</artifactId> <version>1.0.9</version> </dependency> |
В результате пользовательский интерфейс Swagger будет извлечен через веб-файлы и сгенерирован файл index.html из шаблона, который можно настроить с помощью API-интерфейса MicroProfile Config .
Просто добавив выше, вы получите интерфейс по умолчанию, например:
HTTP: // локальный: 8080 / пример / API / OpenAPI-щ /
Персонализируйте свой интерфейс
Используя Config API, вы можете персонализировать пользовательский интерфейс. Вот ключи конфигурации, которые вы можете использовать:
- openapi-ui.copyrightBy — добавляет имя к авторскому праву в нижнем колонтитуле. По умолчанию нет.
- openapi-ui.copyrightYear — добавляет год авторского права. По умолчанию текущий год.
- openapi-ui.title — добавляет заголовок в окно. По умолчанию используется «MicroProfile — Open API».
- openapi-ui.serverInfo — добавляет информацию на сервер. По умолчанию используется информация о системном сервере.
- openapi-ui.contextRoot — добавляет корневой контекст. По умолчанию используется текущее значение.
- openapi-ui.swaggerUiTheme — используйте тему из swagger-ui-themes. По умолчанию «flattop».
- openapi-ui.swaggerHeaderVisibility — Показать / скрыть заголовок логотипа чванства. По умолчанию «видимый».
- openapi-ui.exploreFormVisibility — Показать / скрыть форму исследования. По умолчанию «скрытый».
- openapi-ui.serverVisibility — Показать / скрыть выбор сервера. По умолчанию «скрытый».
- openapi-ui.createdWithVisibility — Показать / скрыть созданное с нижнего колонтитула. По умолчанию «видимый».
Пример: добавление этого в META-INF/microprofile.properties
|
1
2
3
4
|
openapi-ui.copyrightBy=Phillip Kruger openapi-ui.title=My awesome services openapi-ui.swaggerHeaderVisibility=hidden openapi-ui.serverVisibility=visible |
изменит интерфейс:
тема
Пользовательский интерфейс по умолчанию использует тему flattop из swagger-ui-themes , но вы также можете изменить это:
|
1
|
openapi-ui.swaggerUiTheme=monokai |
логотип
Наконец, вы можете изменить логотип на логотип вашей компании, включив файл с именем openapi.png в /src/main/resources/ :
Apiee
Для серверов приложений, которые не имеют MicroProfile, см. Apiee
| Опубликовано на Java Code Geeks с разрешения Филиппа Крюгера, партнера нашей программы JCG . Смотрите оригинальную статью здесь: Swagger UI на MicroProfile OpenAPI
Мнения, высказанные участниками Java Code Geeks, являются их собственными. |