Я обновил Swagger до новой версии, но не ожидал, что будет столько ям!

Spring Boot Java
Я обновил Swagger до новой версии, но не ожидал, что будет столько ям!

Адрес фактического центра электронной коммерции SpringBoot (35k+star):GitHub.com/macro-positive/…

Резюме

посмотри наmallСтарый стиль документации Swagger API в проекте, в этот раз я наконец-то решил его обновить. В процессе обновления есть много подводных камней, но при правильном использовании Maven это не проблема!

Выберите версию обновления

Сначала мы выбираем версию, которую необходимо обновить, и переходим непосредственно в репозиторий Maven, чтобы посмотреть, какая версия используется больше. Хотя последняя версия2.10.x, но его почти никто не использует, а предыдущая версия2.9.xЕсть много людей, которые используют его, но кажется, что2.9.xВерсия относительно стабильная, мы выбираем обновление до2.9.2Версия.

Обновить Сваггер

Далее мы можем приступить к обновлению версии Swagger.Исходный проект использовал2.7.0Версия.

  • так какmallПроект использует родительский проект для унифицированного управления зависимостями, поэтому просто измените версию зависимостей Swagger в родительском проекте, а файл pom.xml родительского проекта находится в корневом каталоге проекта;
<properties>
    <swagger2.version>2.9.2</swagger2.version>
</properties>
  • бегатьmall-adminПроект обнаружил, что не может быть запущен, и сообщение об ошибке было следующим: не удалось найти метод в зависимости, на первый взгляд, это былоguavaВнутри предполагается, что это проблема версии;
***************************
APPLICATION FAILED TO START
***************************

Description:

An attempt was made to call a method that does not exist. The attempt was made from the following location:

    springfox.documentation.schema.DefaultModelDependencyProvider.dependentModels(DefaultModelDependencyProvider.java:79)

The following method did not exist:

    com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;

The method's class, com.google.common.collect.FluentIterable, is available from the following locations:

    jar:file:/C:/Users/macrozheng/.m2/repository/com/google/guava/guava/18.0/guava-18.0.jar!/com/google/common/collect/FluentIterable.class

It was loaded from the following location:

    file:/C:/Users/macrozheng/.m2/repository/com/google/guava/guava/18.0/guava-18.0.jar


Action:

Correct the classpath of your application so that it contains a single, compatible version of com.google.common.collect.FluentIterable


Process finished with exit code 1
  • Когда есть несколько зависимостей, использующих разные версииguavaКак Maven выбирает пакет? Maven выбирается по принципу близости, и чем мельче уровень, тем больше шансов, что он будет выбран;

  • Рекомендуется использоватьMaven HelperЭтот плагин IDEA, прямой просмотрmall-adminЕсли в проекте есть конфликт зависимостей, версия гуавы действительно конфликтует;

  • Его можно найти путем наблюденияminioЭтот уровень зависимости является самым поверхностным, поэтому используется его версия для гуавы, и его можно исключить напрямую;
<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <exclusions>
        <exclusion>
            <artifactId>guava</artifactId>
            <groupId>com.google.guava</groupId>
        </exclusion>
    </exclusions>
</dependency>
  • После завершения исключения обнаруживается, что конфликт зависимостей гуавы исчез, запустите его сноваmall-adminУстановлено, что проект работает нормально;

  • Когда мы получили доступ к документу Swagger, мы обнаружили другую проблему, и было сообщено об исключении NumberFormatException;
java.lang.NumberFormatException: For input string: ""
	at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)
	at java.lang.Long.parseLong(Long.java:601)
	at java.lang.Long.valueOf(Long.java:803)
	at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412)
  • Причина в том, что когда мы используем аннотацию @ApiModelProperty в качестве типа данных Long, если вы не добавитеexampleProperty, значением по умолчанию является пустая строка, и преобразование пустой строки, естественно, сообщит об исключении NumberFormatException;
/**
 * 修改订单费用信息参数
 * Created by macro on 2018/10/29.
 */
@Getter
@Setter
public class OmsMoneyInfoParam {
    @ApiModelProperty(value = "订单ID",example = "1")
    private Long orderId;
}
  • Мы использовали много аннотаций @ApiModelProperty, их невозможно добавить по одной, но с новой версиейswagger-annotationsиswagger-modelsПакет зависимостей можно решить, поэтому наша зависимость Swagger становится следующей:
<dependencies>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <exclusions>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-annotations</artifactId>
            </exclusion>
            <exclusion>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
    </dependency>
    <!--解决Swagger 2.9.2版本NumberFormatException-->
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.6.0</version>
    </dependency>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.6.0</version>
    </dependency>
</dependencies>

  • бежать сноваmall-adminВыяснено, что проблема решена.Как только мы обнаружим неподходящие зависимости в maven, мы их устраним, а затем введем соответствующие версии зависимостей.Хорошо ли это делать?

  • Фактически, мы можем использовать функцию наследования проекта Maven, чтобы напрямую указать версию зависимости в родительском проекте, чтобы можно было унифицировать версии зависимостей подпроектов;

  • поставь оригиналpom.xmlКонфигурация, исключающая guava и swagger, удаляется, а затем изменяется файл pom.xml в корневом каталоге, чтобы указать номер версии;

<properties>
    <swagger2.version>2.9.2</swagger2.version>
    <swagger-models.version>1.6.0</swagger-models.version>
    <swagger-annotations.version>1.6.0</swagger-annotations.version>
    <guava.version>20.0</guava.version>
</properties>
  • Добавьте соответствующие зависимости, которым требуется унифицированное управление, в узел управления зависимостями родительского проекта, и обновление версии Swagger будет завершено;
<dependencyManagement>
    <dependencies>
        <!--Swagger-UI API文档生产工具-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <!--解决Swagger 2.9.2版本NumberFormatException-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>${swagger-models.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger-annotations.version}</version>
        </dependency>
        <!--统一Guava版本防止冲突-->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>${guava.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>
  • Когда мы настроим Token для доступа к интерфейсу, требующему разрешения, мы обнаружим, что интерфейс под брендом, продуктом и категорией продукта имеет разрешение на доступ, а другие подсказки не имеют разрешения, потому что мы использовали следующую конфигурацию для настройки путь, требующий аутентификации при входе в систему;
@Configuration
@EnableSwagger2
public class Swagger2Config {

    private List<SecurityContext> securityContexts() {
        //设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/brand/.*"));
        result.add(getContextByPath("/product/.*"));
        result.add(getContextByPath("/productCategory/.*"));
        return result;
    }
}
  • Вы можете изменить его на все пути. Это немного отличается от старой версии. Старая версия обращается ко всем интерфейсам с токеном в информации заголовка, а новая версия будет содержать токен только для настроенного пути.
@Configuration
@EnableSwagger2
public class Swagger2Config {
    private List<SecurityContext> securityContexts() {
        //设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/*/.*"));
        return result;
    }
}

Сравнение интерфейса новой и старой версии

После того, как Swagger обновился до версии 2.9.2, интерфейс сразу стал красивым, давайте сравним старый и новый интерфейсы.

старая версия

новая версия

Адрес исходного кода проекта

GitHub.com/macro-positive/…

публика

проект торгового центраПолный набор учебных пособий сериализуется,Обратите внимание на общедоступный номерПолучите это прямо сейчас.

公众号图片

Категории