Что такое Swagger?

Swagger — это инструмент, который автоматически генерирует онлайн-документацию и позволяет отлаживать интерфейсы. В веб-разработке мы должны предоставлять клиентам API-интерфейсы, и для этого можно использовать такие инструменты, как Postman или Rap. С помощью Swagger вы можете избавиться от утомительного процесса настройки POST-запросов с множеством параметров.

Проектная группа

В последнее время всё больше людей интересуются проектом swagger-spring-boot-starter, поэтому была создана группа обратной связи (QQ: 868804589), где можно обсуждать проблемы с BUG и предложения по оптимизации и улучшению.

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

GitHub: https://github.com/battcn/swagger-spring-boot Код Cloud: https://gitee.com/battcn/spring-boot-starter-swagger/

swagger-spring-boot-starter — это набор инструментов, основанный на Swagger и использующий возможности SpringBoot для упрощения традиционной конфигурации Swagger.

Описание проекта

• swagger-vue — исходный код, написанный на Vue. Если у вас есть идеи по улучшению пользовательского интерфейса, вы можете расширить этот проект.
• swagger-vue-ui — скомпилированный чистый HTML-файл. Если вам не нравится UI в пакете swagger-spring-boot-starter, вы можете исключить swagger-vue-ui и использовать сторонние решения.
• swagger-spring-boot-starter — пакет расширения для автоматического подключения Swagger.

Если вы хотите расширить свой собственный Starter-пакет, обратитесь к статье «Написание собственного starter-проекта».

Использование

1. В версиях до X необходимо добавить @EnableSwagger2Doc в класс запуска, но после версии 2.X это не требуется.

— В файле pom.xml добавьте зависимость:

<dependency>
    <groupId>com.battcn</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.1.5-RELEASE</version>
</dependency>

2. Если возникают проблемы с кодировкой на китайском языке, убедитесь, что ваши ресурсы закодированы в UTF-8, и добавьте следующие настройки (обычно достаточно правильной настройки среды, дополнительные настройки не требуются):

server.tomcat.uri-encoding=UTF-8
spring.http.encoding.force=true
spring.http.encoding.enabled=true
spring.http.encoding.charset=UTF-8
spring.messages.encoding=UTF-8

3. Если доступ к swagger-ui.html приводит к ошибке 404, попробуйте следующее решение:

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * Решение проблемы доступа к пути swagger-ui.html 404
 *
 * @author Levin
 */
@Configuration
public class SwaggerMvnConfiguration extends WebMvcConfigurationSupport {

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/META-INF/resources/").setCachePeriod(0);
    }
}

4. В файле application.yml добавьте:

spring:
  swagger:
    enabled: true

5. В файле application.properties добавьте:

spring.swagger.enabled=true

История обновлений

2.1.5 (опубликовано 04.03.2019)

• Исправление текущих проблем.
• Добавление функции поиска по интерфейсу.
• Оптимизация кода VUE.
• Обсуждение с компанией Frontend-экспертом вопросов рефакторинга кода и рендеринга нового пользовательского интерфейса. Версия 2.1.5 является наиболее стабильной версией без ошибок.

2.1.3 (опубликовано 27.12.2018)

• Исправлено: при использовании многоуровневого content-path возникает ошибка 404.
• Исправлено: при вложении сущностей неправильно отображаются обязательные поля @ApiModelProperty.
• Исправлено: проблема с отсутствием отступов в новом пользовательском интерфейсе.
• Исправлено: когда количество интерфейсов слишком велико, не появляется полоса прокрутки.
• Когда интерфейс имеет тип JAVA POJO, объекты, отображаемые в пользовательском интерфейсе, имеют цветовую дифференциацию.
• Пользовательский интерфейс адаптируется и становится более удобным для просмотра на разных разрешениях экрана.
• Поддержка совместимости пользовательского интерфейса с IE11, EDGE и другими браузерами.
• Извинения за задержку выпуска из-за занятости.

2.1.2 (опубликовано 14.11.2018)

• Решена проблема, когда данные строкового типа не отображаются в панели отладки.

• Решено: когда параметры запроса являются JSONObject, они не передаются как JSON.

• Панель отладки может добавлять значения по умолчанию для параметров запроса, используя аннотацию @ApiModelProperty example. @Api: обычно используется в Controller для группировки интерфейсов. (Например: @Api(value = "用户接口", description = "用户接口", tags = {"1.1.0"}))

• @ApiOperation: описание интерфейса, используется на методах API. (Например: @ApiOperation(value = "用户查询", notes = "根据ID查询用户信息"))

• @ApiImplicitParam: описание параметра, подходит для одного основного параметра запроса.

• @ApiImplicitParams: описание нескольких параметров, основные параметры описаны выше в @ApiImplicitParam.

• @ApiModel: описание класса сущности.

• @ApiModelProperty: описание свойства сущности.

Как участвовать

Все заинтересованные могут связаться со мной (Pull Request), чтобы присоединиться к разработке и улучшить пользовательский интерфейс и настройки.