Откажитесь от уродливого swagger-ui, используйте артефакт генерации документа интерфейса ножа

Java

[TOC]

нож Gitee адрес:git ee.com/Little Wildcat/ Посмотрите на свой пост…

Введение в инструмент ножа для создания интерфейса

В предыдущем проекте swagger использовался для генерации фоновых интерфейсных документов, что очень просто в использовании, по крайней мере удобнее, чем написание интерфейсных документов postman отладки интерфейса в word раньше. swagger предоставляет набор интерфейсных страниц, но вам необходимо добавить аннотации к коду, такие как:@Api @ApiOperationИ т. д., степень связи относительно высока, но очень удобна в использовании. Для моего обсессивно-компульсивного расстройства страница swagger-ui выглядит крайне уродливо, и мне кажется, что она очень грязная, и нет возможности сохранить часто используемые параметры, что очень неудобно в использовании.

Эта статья познакомитknife, расширенная версия swagger. Пакет улучшения пользовательского интерфейса в основном включает две основные функции:ДокументацияиОнлайн-отладка

  • Документация: В соответствии со спецификацией Swagger подробно перечислите описание документа интерфейса, включая адрес интерфейса, тип, пример запроса, параметр запроса, пример ответа, параметр ответа, код ответа и другую информацию.Использование ножа может в соответствии с описанием документа, интерфейс Использование понятно с первого взгляда.
  • Онлайн-отладка: Предоставляет мощную функцию совместной отладки онлайн-интерфейса, автоматически анализирует текущие параметры интерфейса, а также включает проверку формы.Параметры вызова могут возвращать такую ​​информацию, как содержимое ответа интерфейса, заголовки, экземпляр команды запроса Curl, время ответа, код состояния ответа, и т. д., чтобы помочь разработчикам отлаживать онлайн., без необходимости проверять правильность интерфейса с помощью других инструментов тестирования, кратких и мощных. И может кэшировать параметры запроса, устанавливать заголовок или запрашивать глобальные параметры и значения.

Функции не представлены слишком много, просто покажите картинку выше напрямую:

интеграционный нож springboot

Базовый фреймворк Springboot не будет слишком подробно представлен, он непосредственно продемонстрирует конфигурацию, которую необходимо изменить, чтобы Springboot интегрировал нож.

файл pom.xml для добавления зависимостей

Так как этоspringfox-swaggerРасширенный пакет пользовательского интерфейса, поэтому основные функции по-прежнему зависят отswagger,springfox-swaggerПакет jar должен быть импортирован. затем импортироватьknife4j-spring-uiзаменить оригиналswagger-ui.

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>3.0.2</version>
</dependency>

Написать файл конфигурации Swagger2Config

Содержимое файла Swagger2Config выглядит следующим образом:

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("台接口")
                .description("这里描述内容")
                .contact(new Contact("Liuyanmin", "", ""))
                .termsOfServiceUrl("http://localhost:60000/")
                .version("1.0")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .host("http://localhost:60000/")
                .groupName("后台接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

адрес,knifeАдрес доступа по умолчанию:http://${host}:${port}/doc.html

swagger-uiСтраница стилей по-прежнему доступна, адрес:http://${host}:${port}/swagger-ui.html, это не рекомендуется, страница слишком некрасивая, просто поймите это.

Меры предосторожности

Доступ в SpringBootdoc.htmlилиswagger-ui.htmlРешение для отчета 404

@Configuration
public class IntercpetorConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 设置swagger静态资源访问
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

Springfox-swaggerИнтерфейс, предоставляемый по умолчанию, и зависимые файлы ресурсов необходимо отфильтровать в перехватчике или при проверке разрешений.Содержимое фильтрации выглядит следующим образом:

/swagger-ui.html,/swagger-resources/**,/csrf,/webjars/**

Суммировать

Если проект уже использовалсяswaggerСгенерируйте документацию по интерфейсу, измените наknifeНа самом деле это очень просто, всего два шага:

  1. поместить в pom.xmlswagger-uiпакет jar заменяется наknife4j-spring-ui
  2. адрес доступа из оригиналаhttp://${host}:${port}/swagger-ui.htmlизменить наhttp://${host}:${port}/doc.html

Это так просто.

Есть и другие превосходные инструменты для генерации документов с открытым исходным кодом, вы можете взглянуть на них, если вам интересно.

gitbook

smart-doc

redoc

yapi

apidoc

showdoc

Категории