Официальный стартер Swagger 3.0 родился, вы можете выбросить эти дикие стартеры

Java

Оригинал: Ape Logic, добро пожаловать, пожалуйста, сохраните источник для перепечатки.

SwaggerЭто хороший помощник для исследований и разработок, который может значительно снизить затраты на связь на переднем и заднем концах. Даже в некоторых более продвинутых компаниях это может снизить стоимость общения с тестировщиками. Поэтому, пока в проекте используется среда SpringBoot, Swagger является почти обязательным компонентом.

К сожалению, Swagger — это всего лишь инструмент. При интеграции его нужно модифицироватьpomфайл, добавьте два пакета jar. Еще нужно заняться настройкой, неудачные проекты еще нужно доработатьWebMvcConfigurerсодержание в .

В SpringBoot, если это более проблематично, вы можете написать начальный компонент для решения этой проблемы. По этим многочисленным причинам для Swagger было много диких стартеров. Глядя на странные упаковки банок, представленные в проекте, в голове чистых людей всегда возникают какие-то неестественные вещи.

Давайте взглянем,Swagger3.0Как это используется в SpringBoot.

Добавьте начальные зависимости к pom.xml.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Доступ в вашем браузере:

http://localhost:8080/swagger-ui/

У вас может быть функция документации (да, не swagger-ui.html). законченный? Сделанный. Это так просто. Некоторые люди говорят, что его нужно добавить в основной класс.@EnableOpenApiАннотация на самом деле не нужна.

Какие изменения?

Видно, что настройка Swagger3 в SpringBoot непростая. важнееio.springfoxТакое название пакета выглядит высоким и высоким, и люди не могут не испытывать чувство доверия.

Swagger делает следующее в 3.0:

  • Удалены подробные зависимости pom, в том числеspringfox-swagger2
  • убит@EnableSwagger2Аннотации, нулевая конфигурация
  • Удалено много зависимостей, таких как гуава, более освежающий

На самом деле все делается в файле AutoConfig, как и у других стартеров. Из исходного кода мы обнаружили, что компоненты swagger и ui включены по умолчанию.

springfox.documentation.enabledконфигурации, вы можете отключить его одним щелчком мыши.springfox.documentation.swagger-ui.enabledПараметры, вы можете управлять отображением пользовательского интерфейса.

Из зависимостей Swagger мы видим более интересную концепцию: openAPI. У этой штуки даже есть Спецификация. Видно, что документация является болевой точкой не только старомодных проектных компаний, но и Интернета.

https://swagger.io/specification/

Статья очень длинная, назовем спецификацию пока документом О_О документа.

О сертификации

Конечно, есть изменения. Если вы используете Spring Security, компонент контроля разрешений в своем проекте, не забудьте добавить белый список. Аналогично приведенному ниже.

String[] SWAGGER_WHITELIST = {
        "/swagger-ui.html",
        "/swagger-ui/*",
        "/swagger-resources/**",
        "/v2/api-docs",
        "/v3/api-docs",
        "/webjars/**"
};
httpSecurity.cors()
        .antMatchers(SWAGGER_WHITELIST).permitAll()

Адрес swagger за ним, вы также можете получить доступ к v2 и v3. Во всяком случае, я импортирую платформы управления API, такие как yapi и rap2, и все работает.

Интеграция стала проще, но аннотация ApiOperation все так же безобразна.

Иногда, когда мы используем метод аутентификации, такой как JWT, нам нужно создать токен в заголовке при запросе.

Swagger поддерживает два способа.

Первый — через глобальную конфигурацию аутентификации Auth.

Как показано выше, нажмите кнопку Auth в правом верхнем углу, чтобы открыть диалоговое окно.

В этот момент вам необходимоSwaggerConfigфайл. Ниже приведен полный код.

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .build()
                .securitySchemes(security());
    }
private List<SecurityScheme> security() {
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        return Collections.singletonList(apiKey);
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("mbye api")
                .description("nothing here")
                .version("1.0")
                .build();
    }
}

Во-вторых, вам нужно вручную вводить токен каждый раз, когда вы запрашиваете. Аналогично следующему:

Конфигурация выглядит следующим образом:

private List<RequestParameter> globalRequestParameters() {
    RequestParameterBuilder parameterBuilder = new RequestParameterBuilder()
            .in(ParameterType.HEADER)
            .name("Authorization")
            .required(false)
            .query(param -> param.model(model -> model.scalarModel(ScalarType.STRING)));
    return Collections.singletonList(parameterBuilder.build());
}

Просто используйте код ниже.

.globalRequestParameters(globalRequestParameters());

End

Короче говоря, общее ощущение по-прежнему очень хорошо. Это может быть моя иллюзия, я думаю, что страница также намного более гладкая. Но так как новая версия еще относительно новая, в ней много мелких багов. Например, страница аутентификации прошла успешно, но в параметре запроса curl нет значения.

Тем не менее, swagger3 все же стоит попробовать. Более того, стоимость его изменений почти ничего не стоит.

​

Категории