Поменял новый скин на Swagger, и мгновенно стал выше!

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

Резюме

Swagger, как инструмент генерации документов API, хотя функция очень полная, все же есть некоторые недостатки. Я случайно обнаружил, что knife4j восполняет эти недостатки и дает Swagger больше функций, о том, как им пользоваться, мы сегодня и поговорим.

Знакомство с ножом4j

knife4j — это улучшенная реализация пользовательского интерфейса springfox-swagger, которая обеспечивает краткую и мощную документацию по интерфейсу для разработчиков Java при использовании Swagger. knife4j полностью повторяет использование в springfox-swagger и вносит улучшения на этой основе.Если вы использовали Swagger, вы можете легко переключиться на knife4j.

быстрый старт

Далее давайте познакомимся с тем, как использовать knife4j в SpringBoot, всего в два шага!

• Добавьте соответствующие зависимости knife4j в pom.xml;

<!--整合Knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version>
</dependency>

• Добавьте аннотацию @EnableKnife4j в Swagger2Config, которая активирует расширение knife4j;

/**
 * Swagger2API文档的配置
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {
    
}

• Запустите наше приложение SpringBoot и посетите адрес документации API, чтобы просмотреть:http://localhost:8088/doc.html

Функции

Далее давайте сравним Swagger и посмотрим, чем отличается от него использование knife4j!

Улучшения JSON

Я использую Swagger все время, но поддержка JSON у Swagger была не очень хорошей, JSON нельзя свернуть, и он слишком длинный для чтения, при передаче параметров в формате JSON отсутствует функция проверки параметров. Эти болевые точки были решены на knife4j.

• Возвращаемый набор результатов поддерживает свертывание для удобства просмотра;

• Параметры запроса имеют функцию проверки JSON.

аутентификация входа

knife4j также поддерживает добавление токена в заголовок для аутентификации при входе.

• первый вAuthorizeДобавьте Token, возвращенный при входе в функцию;

• После этого в каждом интерфейсе вы можете увидеть, что информация о токене была перенесена в заголовок запроса.

Автономная документация

knife4j поддерживает экспорт автономных документов для удобной отправки другим и поддерживает формат Markdown.

• прямой выбор文档管理->离线文档функцию, затем выберите下载MarkdownТы сможешь;

• Давайте взглянем на экспортированный автономный документ Markdown, который по-прежнему очень подробен.

глобальные параметры

knife4j поддерживает временную настройку глобальных параметров и поддерживает два типа запроса (форма) и заголовок (заголовок запроса).

• Например, если мы хотим добавить параметр appType ко всем заголовкам запросов, чтобы различать, является ли это вызовом android или ios, мы можем добавить его в глобальный параметр;

• В этот момент, когда интерфейс вызывается снова, он будет содержатьappTypeэтот заголовок запроса.

Игнорировать свойства параметра

Иногда интерфейс, который мы создаем и модифицируем, будет использовать тот же объект, что и параметр запроса, но нам не нужен идентификатор при его создании и нам нужен идентификатор при его изменении.В этом случае мы можем игнорировать атрибут id.

• Например, в интерфейсе создания продукта здесь идентификатор, количество продуктов и количество обзоров продуктов могут быть сгенерированы фоновым интерфейсом без передачи, и вы можете использовать интерфейс, предоставляемый knife4j.@ApiOperationSupportаннотация для игнорирования этих свойств;

/**
 * 品牌管理Controller
 * Created by macro on 2019/4/19.
 */
@Api(tags = "PmsBrandController", description = "商品品牌管理")
@Controller
@RequestMapping("/brand")
public class PmsBrandController {
    @Autowired
    private PmsBrandService brandService;

    private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);

    @ApiOperation("添加品牌")
    @ApiOperationSupport(ignoreParameters = {"id","productCount","productCommentCount"})
    @RequestMapping(value = "/create", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
        CommonResult commonResult;
        int count = brandService.createBrand(pmsBrand);
        if (count == 1) {
            commonResult = CommonResult.success(pmsBrand);
            LOGGER.debug("createBrand success:{}", pmsBrand);
        } else {
            commonResult = CommonResult.failed("操作失败");
            LOGGER.debug("createBrand failed:{}", pmsBrand);
        }
        return commonResult;
    }
}

• При просмотре документа интерфейса в это время обнаруживается, что эти три атрибута исчезли, так что фронтенд-разработке не будет казаться, что вы определяете бесполезные параметры при просмотре документа интерфейса, что является не очень хорошей функцией!

использованная литература

Официальная документация:doc.xiaominfo.com/guide/

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

GitHub.com/macro-positive/…

публика

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