简介

Данный проект использует автоматизированную конфигурацию Spring Boot для быстрого внедрения Swagger 2 в приложения Spring Boot и создания документации API. Это упрощает интеграцию с Swagger 2 по сравнению с использованием его напрямую.

Исходный код:
- GitHub: https://github.com/dyc87112/spring-boot-starter-swagger
- Кодовый облачный сервис: https://gitee.com/didispace/spring-boot-starter-swagger
Пример использования: https://github.com/dyc87112/swagger-starter-demo
Мой блог: http://blog.didispace.com
Наше сообщество: http://www.spring4all.com

Это небольшой инструмент, который можно использовать и поддерживать. Если у вас возникнут проблемы при использовании, вы можете создать Issue, и я постараюсь улучшить этот Starter.

Основы версии

SpringFox Swagger: 3.0.0

Как использовать

С помощью этого проекта мы можем легко внедрить Swagger 2 в наш Spring Boot. Для этого нужно выполнить следующие шаги:

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

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>2.0.2.RELEASE</version>
</dependency>

Примечание:

Начиная с версии 1.6.0, мы изменили artifactId на swagger-spring-boot-starter по рекомендации Spring Boot. Предыдущие версии не требуют изменений и могут продолжать использовать spring-boot-starter-swagger.
Начиная с версии 2.0.0, больше не требуется вручную добавлять @EnableSwagger2Doc для запуска конфигурации Swagger.

По умолчанию будет создан документ для всех текущих запросов Spring MVC.

Конфигурация параметров

Более подробные настройки описаны ниже:

Примеры конфигурации

springfox.documentation.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
swagger.contact.email=dyc87112@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

swagger.globalOperationParameters[0].name=name one
swagger.globalOperationParameters[0].description=some description one
swagger.globalOperationParameters[0].modelRef=string
swagger.globalOperationParameters[0].parameterType=header
swagger.globalOperationParameters[0].required=true
swagger.globalOperationParameters[1].name=name two
swagger.globalOperationParameters[1].description=some description two
swagger.globalOperationParameters[1].modelRef=string
swagger.globalOperationParameters[1].parameterType=body
swagger.globalOperationParameters[1].required=false

// Отменяем использование стандартных сообщений об ответах и используем собственные сообщения об ответах
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

Описание конфигурации

Базовая конфигурация

springfox.documentation.enabled=Включает или отключает Swagger, по умолчанию: true

swagger.title=Заголовок
swagger.description=Описание
swagger.version=Версия
swagger.license=Лицензия
swagger.licenseUrl=URL лицензии
swagger.termsOfServiceUrl=URL условий обслуживания

swagger.contact.name=Имя сопровождающего
swagger.contact.url=URL сопровождающего
swagger.contact.email=Электронная почта сопровождающего

swagger.base-package=Базовый пакет для сканирования Swagger, по умолчанию: сканирование всего
swagger.base-path=Основной URL-адрес, требующий обработки, по умолчанию: /**
swagger.exclude-path=Исключаемые URL-адреса, по умолчанию: пустые

swagger.host=Информация о хосте документа, по умолчанию: пустая

swagger.globalOperationParameters[0].name=Имя параметра
swagger.globalOperationParameters[0].description=Информационное описание
swagger.globalOperationParameters[0].modelRef=Указывает тип параметра
swagger.globalOperationParameters[0].parameterType=Указывает место хранения параметра (можно выбрать header, query, path, body.form)
swagger.globalOperationParameters[0].required=Определяет, является ли параметр обязательным для передачи, true, false

Начиная с версии 1.3.0.RELEASE, добавлен атрибут swagger.host, который также поддерживает настройку docket.

В версии 1.4.0.RELEASE добавлены:

swagger.enabled: используется для управления конфигурацией Swagger;

swagger.globalOperationParameters: используется для установки глобальных параметров, таких как параметры заголовка accessToken и т. д. Этот параметр поддерживает настройку docket.

Версия 2.0.0.RELEASE изменена:

Предыдущая конфигурация swagger.enabled изменена на springfox.documentation.enabled, чтобы контролировать её. Когда у проекта очень много API, мы хотим разделить API-документы на группы. Начиная с версии 1.2.0.RELEASE будет поддерживаться функция настройки групп.

Конкретные настройки следующие:

swagger.docket.<name>.title=Заголовок
swagger.docket.<name>.description=Описание
swagger.docket.<name>.version=Версия
swagger.docket.<name>.license=Лицензия
swagger.docket.<name>.licenseUrl=URL лицензии
swagger.docket.<name>.termsOfServiceUrl=URL условий обслуживания
swagger.docket.<name>.contact.name=Имя сопровождающего
swagger.docket.<name>.contact.url=URL сопровождающего
swagger.docket.<name>.contact.email=Электронная почта сопровождающего
swagger.docket.<name>.base-package=Базовый пакет для сканирования Swagger, по умолчанию: полное сканирование
swagger.docket.<name>.base-path=Основной URL-адрес для обработки, по умолчанию: /**
swagger.docket.<name>.exclude-path=Исключаемые URL-адреса, по умолчанию: пусто
swagger.docket.<name>.name=Название
swagger.docket.<name>.modelRef=Указанный тип параметра
swagger.docket.<name>.parameterType=Указывает местоположение параметра, можно выбрать header, query, path, body.form
swagger.docket.<name>.required=true=указывает, является ли параметр обязательным для передачи, true, false
swagger.docket.<name>.globalOperationParameters[0].name=Название параметра
swagger.docket.<name>.globalOperationParameters[0].description=Информация об описании
swagger.docket.<name>.globalOperationParameters[0].modelRef=Указать местоположение параметра, можно выбрать header, query, path, body.form
swagger.docket.<name>.globalOperationParameters[0].parameterType=Укажите, является ли параметр обязательным, true, false

Примечание: <name> — это имя группы документов Swagger в проекте, и в одном проекте можно настроить несколько групп для разделения различных документов API.

Пример конфигурации группы

swagger.docket.aaa.title=group-a
swagger.docket.aaa.description=Starter for swagger 2.x
swagger.docket.aaa.version=1.3.0.RELEASE
swagger.docket.aaa.termsOfServiceUrl=https://gitee.com/didispace/spring-boot-starter-swagger
swagger.docket.aaa.contact.name=zhaiyongchao
swagger.docket.aaa.contact.url=http://spring4all.com/
swagger.docket.aaa.contact.email=didi@potatomato.club
swagger.docket.aaa.excludePath=/ops/**
swagger.docket.aaa.globalOperationParameters[0].name=name three
swagger.docket.aaa.globalOperationParameters[0].description=some description three override
swagger.docket.aaa.globalOperationParameters[0].modelRef=string
swagger.docket.aaa.globalOperationParameters[0].parameterType=header

swagger.docket.bbb.title=group-bbb
swagger.docket.bbb.basePackage=com.yonghui

Примечание. Конфигурации по умолчанию и групповые конфигурации могут использоваться вместе. Если в групповой конфигурации не настроено содержимое, то будет использоваться конфигурация по умолчанию для замены, поэтому конфигурация по умолчанию может использоваться как общая конфигурация атрибутов для групповых конфигураций. swagger.docket.aaa.globalOperationParameters[0].name переопределит одноимённую глобальную конфигурацию.

Поддержка проверки аннотаций JSR-303 (поддерживается с 1.5.0)

Поддерживает отображение аннотаций проверки JSR-303, как показано на рисунке ниже:

Демонстрация проверки JSR-303

В настоящее время поддерживаются следующие аннотации:

@NotNull
@Max、@Min
@Size
@Pattern

Поддержка пользовательских глобальных сообщений ответа (поддерживается с 1.6.0)

Поддержка POST, GET, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE глобальной конфигурации сообщений ответа, настройка следующая:

// Отключить использование предопределённых сообщений по умолчанию и использовать настраиваемые сообщения ответа
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.global-response-message.post[0].modelRef=ERROR

Настройка функций пользовательского интерфейса (поддерживается с 1.6.0)

— Управление отладкой (попробуйте)

swagger.ui-config.submit-methods=get,delete

Этот параметр указывает типы HTTP-запросов для предоставления кнопок отладки, разделенных запятыми.

Если вы не хотите включать функцию отладки, просто выполните следующую настройку:

swagger.ui-config.submit-methods=

— Другие настройки

# Редактор JSON
swagger.ui-config.json-editor=false

# Отображение заголовков запросов
swagger.ui-config.show-request-headers=true

# Время ожидания запроса страницы
swagger.ui-config.request-timeout=5000

Конфигурация ignoredParameterTypes (поддерживается с 1.6.0)

# Базовая конфигурация
swagger.ignored-parameter-types[0]=com.didispace.demo.User
swagger.ignored-parameter-Types[1]=com.didispace.demo.Product

# Конфигурация группы
swagger.docket.aaa.ignored-parameter-types[0]=com.didispace.demo.User
swagger.docket.aaa.ignored-parameter-types[1]=com.didispace.demo.Product

Этот параметр используется для: Q. Бесконечный цикл при попытке springfox определить схему для объектов со вложенными/сложными ограничениями? A. Если у вас есть рекурсивно определённые объекты, я бы попытался посмотреть, поможет ли предоставление альтернативного типа или, возможно, даже игнорирование оскорбительных классов, например, порядок использования docket. Игноред параметр типс (ордер точка класс). Это обычно встречается в объектах домена гибернации, которые имеют двунаправленные зависимости от других объектов.

Авторизация 鉴权配置 (1.7.0 + поддержка)

Добавление элемента конфигурации авторизации.

# Идентификатор стратегии авторизации, соответствующий идентификатору SecurityReferences
swagger.authorization.name=Authorization

# Тип стратегии авторизации, опционально ApiKey | BasicAuth | None, по умолчанию ApiKey
swagger.authorization.type=ApiKey

# Заголовок, передающий ключ авторизации
swagger.authorization.key-name=token

# Регулярное выражение для URL, требующих авторизации, по умолчанию ^.*$ соответствует всем URL
swagger.authorization.auth-regex=^.*$

Примечание: в настоящее время поддерживаются режимы авторизации ApiKey и BasicAuth, а также режим без авторизации None. По умолчанию используется ApiKey. В будущем будет добавлена поддержка Oauth2.

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

По умолчанию глобально включена функция global SecurityReferences, и никаких дополнительных настроек не требуется;

Область глобальной авторизации можно контролировать с помощью регулярного выражения, соответствующего параметру auth-regex;

Помимо глобального включения, можно вручную определить авторизацию на RestController с помощью аннотаций. Способ использования следующий:

// Здесь ID Authorization — это элемент конфигурации swagger.authorization.name, подробности см. в коде конфигурации ниже
@ApiOperation(value = "Hello World", authorizations = {@Authorization(value = "Authorization")})
@RequestMapping(value = "/hello", method = RequestMethod.GET)
String hello();

О том, как настроить авторизацию, см. код ниже:

/**
 * Конфигурация объекта авторизации на основе ApiKey
 *
 * @return
 */
private ApiKey apiKey() {
    return new ApiKey(swaggerProperties().getAuthorization().getName(),
            swaggerProperties().getAuthorization().getKeyName(),
            ApiKeyVehicle.HEADER.getValue());
}

/**
* Настройка переключателя глобальной стратегии авторизации по умолчанию и сопоставление через регулярное выражение; по умолчанию ^.*$ сопоставляет все URL
* Где securityReferences — активированная стратегия авторизации
*
* @return
*/
private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.regex(swaggerProperties().getAuthorization().getAuthRegex()))
            .build();
}

/**
* Конфигурация глобальной стратегии авторизации по умолчанию; в возвращаемом SecurityReference reference — это имя объекта ApiKey, которое должно быть одинаковым для активации глобальной авторизации
*
* @return
*/
private List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Collections.singletonList(SecurityReference.builder()
            .reference(swaggerProperties().getAuthorization().getName())
            .scopes(authorizationScopes).build());
}

OSCHINA-MIRROR/didispace-spring-boot-starter-swagger

简介

Основы версии

Как использовать

Конфигурация параметров

Примеры конфигурации

Описание конфигурации

Базовая конфигурация

Поддержка проверки аннотаций JSR-303 (поддерживается с 1.5.0)

Поддержка пользовательских глобальных сообщений ответа (поддерживается с 1.6.0)

Настройка функций пользовательского интерфейса (поддерживается с 1.6.0)

Конфигурация ignoredParameterTypes (поддерживается с 1.6.0)

Авторизация 鉴权配置 (1.7.0 + поддержка)

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/didispace-spring-boot-starter-swagger .gitee-modal { min-width: 500px !important; } .gitee-modal .close { right: 0.6rem !important; }

简介

Основы версии

Как использовать

Конфигурация параметров

Примеры конфигурации

Описание конфигурации

Базовая конфигурация

Поддержка проверки аннотаций JSR-303 (поддерживается с 1.5.0)

Поддержка пользовательских глобальных сообщений ответа (поддерживается с 1.6.0)

Настройка функций пользовательского интерфейса (поддерживается с 1.6.0)

Конфигурация ignoredParameterTypes (поддерживается с 1.6.0)

Авторизация 鉴权配置 (1.7.0 + поддержка)

Введение

Обновления

Участники

Недавние действия

OSCHINA-MIRROR/didispace-spring-boot-starter-swagger