Какова функция конфигурации springdoc-openapi-maven-plugin / apiDocsUrl?

Я использую плагин springdoc-openapi-maven-plugin со следующей (стандартной) конфигурацией:

        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>0.2</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

Плагин запускается, но вывода нет.

Я получаю ошибку 404 в выводе Maven:

[INFO] --- springdoc-openapi-maven-plugin:0.2:generate (integration-test) @ paatinc-util-websrv ---
10:40:33.930 [http-nio-8080-exec-1] INFO  o.a.c.c.C.[Tomcat].[localhost].[/] - Initializing Spring DispatcherServlet 'dispatcherServlet'
10:40:33.931 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Initializing Servlet 'dispatcherServlet'
10:40:33.956 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Completed initialization in 25 ms
10:40:33.969 [http-nio-8080-exec-1] INFO  io.paat.util.filter.LoggingFilter - GET http://localhost:8080/v3/api-docs from 127.0.0.1
[ERROR] An error has occured: Response code 404

Из своего журнала я вижу, что 404 звонит по адресу: http://localhost:8080/v3/api-docs

Я также вижу в документации springdoc-openapi-maven-plugin следующую конфигурацию:

 <configuration>
  <apiDocsUrl>http://localhost:8080/v3/api-docs</apiDocsUrl>
  <outputFileName>openapi.json</outputFileName>
  <outputDir>/home/springdoc/maven-output</outputDir>
 </configuration>

Таким образом, похоже, что плагин пытается открыть локальный сервер во время интеграционных тестов и терпит неудачу. Какой в ​​этом смысл? Я думал, что плагин прочитает мои исходные файлы и сгенерирует файл openapi.json. Зачем нужно устанавливать HTTP-соединение с / v3 / api-docs?


java maven spring openapi-generator openapi
person KevinB    schedule 06.01.2020    source источник
comment
Я думал, что плагин прочитает мои исходные файлы и сгенерирует файл openapi.json. - Нет. Плагин запускает приложение и пытается получить доступ к URL-адресу приложения, в котором должен находиться application.json. Я предполагаю, что они заняли позицию кого-то другого, создавшего application.json, нам не нужно создавать его заново. Мы просто запускаем сервер и получаем его.   -  person Turing85    schedule 06.01.2020
comment
Спасибо за ответ. Вы знаете, как я могу сгенерировать только файл openapi.json для моего приложения SpringBoot через Maven?   -  person KevinB    schedule 06.01.2020
comment
Неа. Но дайте мне знать, если узнаете =) У меня такая же проблема.   -  person Turing85    schedule 06.01.2020
comment
В нем прямо говорится, что цель springdoc-openapi-maven-plugin - генерировать описание OpenAPI json и yaml во время сборки. Не имеет смысла ожидать, что он откуда-то это прочитает.   -  person KevinB    schedule 06.01.2020
comment
@ Turing85 Я разобрался. Вот мой проект, который демонстрирует, как сгенерировать openapi.json через Maven во время сборки: github .com / kbaynes / springdoc-maven-plugin-demo. Просто у меня были неправильные зависимости.   -  person KevinB    schedule 06.01.2020
comment
Нет ничего постыдного в том, чтобы ответить на свой вопрос. Из любопытства: не могли бы вы указать мне на необходимые изменения? По-прежнему похоже, что сервер запускается через spring-boot-maven-plugin   -  person Turing85    schedule 06.01.2020
comment
Для меня проблема заключалась в том, что я удалил dep. Я не понимаю, почему сервер все еще работает, хотя я думаю, что это как-то связано с запуском плагина для запуска в рамках «интеграционных тестов».   -  person KevinB    schedule 06.01.2020
comment
Давайте продолжим это обсуждение в чате.   -  person Turing85    schedule 06.01.2020
comment
@KevinB вы ее решили, и если да, то как? У меня здесь точно такая же проблема.   -  person Erdinc Ay    schedule 14.04.2020
comment
Я пробовал ваше решение (я также был миссией основной зависимости), но, похоже, сервер все еще должен быть запущен и работать, что не является временем компиляции. Удалось ли вам это сделать?   -  person dhalfageme    schedule 08.06.2021

Ответы (4)


arrow_upward
6
arrow_downward

Используя springdoc-openapi-ui, вы создаете документацию (html, json и yaml) во время выполнения, когда ваше приложение развернуто.

В некоторых сценариях вам может потребоваться документация во время сборки, и для этого нужен springdoc-openapi-maven-plugin. Для того, чтобы он работал, вам также необходимо, чтобы ваше приложение запускалось с использованием spring -boot на этапе интеграции, как объяснено в документации.

person diegomtassis    schedule 10.04.2020
comment
Это именно то, что касается документации, которая создается во время сборки. Все создается во время выполнения и загружается через http. - person Bragolgirith; 11.05.2020
comment
Да, я все еще получаю это, даже когда следую инструкциям и использую плагин spring boot maven для запуска приложения заранее. - person TheJeff; 10.07.2020

arrow_upward
1
arrow_downward

Хорошо, ребята, поэтому ответ заключается в том, что этот плагин пытается разрешить вашему сервлету Spring загружать из него openapi json во время компиляции. Моя проблема заключалась в том, что я не установил правильный URL-адрес для плагина openapi и, следовательно, ошибку 404.

Журнал от автора задачи:

[http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Initializing Servlet 'dispatcherServlet'
10:40:33.956 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Completed initialization in 25 ms
10:40:33.969 [http-nio-8080-exec-1] INFO  io.paat.util.filter.LoggingFilter - GET http://localhost:8080/v3/api-docs from 127.0.0.1
[ERROR] An error has occured: Response code 404

Хитрость заключается в том, чтобы установить правильный URL-адрес для json в конфигурациях плагинов. Это URL-адрес, по которому ваш json будет во время выполнения (например, когда сервер работает, поэтому измените URL-адрес, порт или что-то еще, что вам нужно):

        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>1.1</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <apiDocsUrl>${url.docs}</apiDocsUrl>
            </configuration>
        </plugin>
person Peeve    schedule 04.11.2020
comment
Первое предложение вашего ответа правильное. Но тогда это может ввести людей в заблуждение, поскольку URL-адрес по умолчанию, который плагин springdoc-openapi генерирует для обслуживания Живая документация по API: http://localhost:8080/v3/api-docs согласно документации. Таким образом, вам нужно только настроить apiDocsUrl, если вы заранее изменили конфигурацию springdoc-openapi plugin. - person jonashackt; 04.11.2020
comment
Нет, другая возможность заключается в том, что вы не запускаете приложение на 8080 по умолчанию, а затем вам нужно изменить apiDocsUrl. Парень получил ошибку 404, поэтому openapi.json не был обслужен по указанному адресу во время компиляции. Поэтому ему нужно изменить apiDocsUrl, как я уже сказал, на место, где будет находиться ваш json во время выполнения. - person Peeve; 04.11.2020
comment
Но, как показывают и авторы, и ваши журналы, приложение работает на 8080;) И еще он попросил стандартную конфигурацию. Если вы используете start.spring.io для создания скелета приложения, вы получите его с пустым файлом application.properties - так что другого порта нет! Настоящий ответ на вопрос заключается в том, что вам необходимо настроить 2 дополнительных плагина maven, чтобы springdoc-openapi-maven-plugin работал (см. stackoverflow.com/ a / 64677754/4964553). - person jonashackt; 04.11.2020

arrow_upward
0
arrow_downward

Сначала добавьте эту зависимость Maven в свой проект:

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.3.2</version>
        <scope>compile</scope>
    </dependency>

Во-вторых, сделайте запускаемый плагин Maven:

    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>pre-integration-test</id>
                    <goals>
                        <goal>start</goal>
                    </goals>
                </execution>
                <execution>
                    <id>post-integration-test</id>
                    <goals>
                        <goal>stop</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>0.3</version>
            <executions>
                <execution>
                    <phase>integration-test</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}/openapi-spec</outputDir>
            </configuration>
        </plugin>
    </plugins>
person Erdinc Ay    schedule 14.04.2020

arrow_upward
0
arrow_downward

И diegomtassis, и Erdinc Да, вместе с этим замечательным сообщением о baeldung я оказался на правильном пути отслеживать.

Суть springdoc-openapi-maven-plugin такова: он не может успешно работать сам по себе - и недостаточно просто добавить его как единственную зависимость к вашему pom.xml!

Плагину нужны 2 другие зависимости, чтобы сделать основу, чтобы он работал:

  1. Вам необходимо добавить плагин springdoc-openapi-ui (для Приложения на основе Tomcat / Spring MVC) ИЛИ springdoc-openapi-webflux-ui (для приложений на основе Reactive WebFlux / Netty) к вашему pom.xml первым!

Вот пример Spring MVC:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.8</version>
</dependency>
  1. Вам необходимо настроить spring-boot-maven-plugin для запуска нашего приложения Spring Boot, включая URL-адрес API, который springdoc-openapi-maven-plugin необходим для создания openapi.json на этапе тестирования интеграции Maven.

Вот необходимая конфигурация уже существующего spring-boot-maven-plugin внутри вашего pom.xml (и нет: здесь вам не нужна версия для этого плагина, поскольку он наследуется от используемого spring-boot-starter-parent):

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <executions>
                <execution>
                    <id>pre-integration-test</id>
                    <goals>
                        <goal>start</goal>
                    </goals>
                </execution>
                <execution>
                    <id>post-integration-test</id>
                    <goals>
                        <goal>stop</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>1.1</version>
            <executions>
                <execution>
                    <phase>integration-test</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Как указано в документации, вы можете настроить такие вещи, как apiDocsUrl, outputDir где openapi.json будет быть размещенным - и даже имя json файла с outputFileName. Но вам не нужно этого делать (в отличие от того, что сказал Пив)!

Теперь, если вы запустите Maven, используя mvn verify (или mvn verify -DskipTests=true, чтобы ускорить выполнение), вы должны увидеть что-то вроде этого:

[INFO] --- spring-boot-maven-plugin:2.3.5.RELEASE:start (pre-integration-test) @ hellobackend ---
[INFO] Attaching agents: []

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v2.3.5.RELEASE)

2020-11-04 10:26:07.246  INFO 42143 --- [           main] i.j.s.SpringBootBuildpackApplication     : Starting SpringBootBuildpackApplication on PikeBook.fritz.box with PID 42143 (/Users/jonashecht/dev/spring-boot/spring-boot-kong/hellobackend/target/classes started by jonashecht in /Users/jonashecht/dev/spring-boot/spring-boot-kong/hellobackend)
2020-11-04 10:26:07.249  INFO 42143 --- [           main] i.j.s.SpringBootBuildpackApplication     : No active profile set, falling back to default profiles: default
2020-11-04 10:26:08.730  INFO 42143 --- [           main] o.s.b.web.embedded.netty.NettyWebServer  : Netty started on port(s): 8080
2020-11-04 10:26:08.742  INFO 42143 --- [           main] i.j.s.SpringBootBuildpackApplication     : Started SpringBootBuildpackApplication in 1.82 seconds (JVM running for 2.318)
[INFO]
[INFO] --- springdoc-openapi-maven-plugin:1.1:generate (default) @ hellobackend ---
2020-11-04 10:26:09.579  INFO 42143 --- [ctor-http-nio-2] o.springdoc.api.AbstractOpenApiResource  : Init duration for springdoc-openapi is: 29 ms
[INFO]
[INFO] --- spring-boot-maven-plugin:2.3.5.RELEASE:stop (post-integration-test) @ hellobackend ---
[INFO] Stopping application...
2020-11-04 10:26:09.661  INFO 42143 --- [on(2)-127.0.0.1] inMXBeanRegistrar$SpringApplicationAdmin : Application shutdown requested.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  23.392 s
[INFO] Finished at: 2020-11-04T10:26:11+01:00
[INFO] ------------------------------------------------------------------------

Наконец, у вас должен быть новый файл openapi.json в папке /target вашего приложения Spring Boot, подобной этой (что было целью использования плагина springdoc-openapi-maven-plugin в первую очередь). Если вам нравится видеть полностью понятный пример проекта, вы можете взглянуть на этот: https://github.com/jonashackt/spring-boot-openapi-kong/tree/main/weatherbackend

person jonashackt    schedule 04.11.2020