SpringBoot интегрирует Swagger3, вам все еще нужен автономный документ? так круто

Spring Boot задняя часть

предисловие

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

существует"Технический директор сказал мне, что в проекте необходимы как минимум эти 3 типа документов.«В статье мы рассказали о важности документации, и документация по интерфейсу — одна из них, о которой можно сказать, что она необходима.

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

Поскольку есть болевая точка, должен быть и продукт, решающий эту болевую точку.Это Swagger, который был обновлен до версии Swagger3. Если вы все еще остаетесь в Swagger2, рекомендуется перейти на Swagger3, общий стиль пользовательского интерфейса и взаимодействие намного более дружелюбны.

В этой статье основное внимание будет уделено интеграции Swagger3 и SpringBoot и созданию автономных документов.

Введение в Swagger

Swagger — это каноническая и полная платформа для создания, описания, вызова и визуализации веб-сервисов в стиле RESTful. Общая цель состоит в том, чтобы клиент и файловая система обновлялись с той же скоростью, что и сервер. Файловые методы, параметры и модели тесно интегрированы в серверный код, что позволяет постоянно синхронизировать API.

Официальный сайт:swagger.io

Болевые точки, решенные Swagger

Традиционный способ предоставления документации имеет следующие болевые точки:

  • Интерфейсов много, детали реализации сложны, написание документов трудоемко, требуется постоянное сопровождение;
  • Документы интерфейса необходимо синхронизировать в любое время;
  • Если результат, возвращаемый интерфейсом, не ясен, необходимо построить возвращаемую структуру и т. д.;
  • Интерфейс нельзя протестировать напрямую онлайн, и обычно требуются дополнительные инструменты, такие как PostMan.

После внедрения Swagger вышеуказанные болевые точки были решены, а также появились следующие преимущества:

  • Своевременность (после изменения интерфейса персонал внешнего и внутреннего интерфейса может видеть последнюю версию в режиме реального времени)
  • Нормативные (конкретный унифицированный стиль интерфейса, такой как адрес интерфейса, метод запроса, параметры, формат ответа и информация об ошибке и т. д.)
  • Согласованность (информация об интерфейсе непротиворечива, и не будет различий из-за версии документа интерфейса)
  • Тестируемость (можно протестировать непосредственно на основе документации интерфейса)

Изменения в Swagger3

Изменения Swagger 3.0, официальный документ резюмирует следующие моменты:

  • Удалена зависимость от springfox-swagger2;
  • Удалить все аннотации @EnableSwagger2...;
  • Добавлена ​​зависимость springfox-boot-starter;
  • Удалены сторонние зависимости, такие как гуава;
  • Адрес доступа к документу изменен наhttp://ip:порт/проект/swagger-ui/index.html.

Используем на практике.

SpringBoot интегрирует Swagger3

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

импортировать зависимости

Внесите зависимость Swagger3 в pom.xml проекта SpringBoot:

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

Укажите файл конфигурации

Обычно swagger можно открыть только в среде разработки или тестовой среде, и его необходимо закрыть в производственной среде. Открытие и закрытие swagger можно настроить в application.properties:

# 生产环境需设置为false
springfox.documentation.swagger-ui.enabled=true

класс конфигурации

Запустите использование Swagger через аннотацию @EnableOpenApi и настройте общие параметры Swagger в классе конфигурации.

@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Bean
    public Docket createRestApi() {
        //返回文档摘要信息
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage());
    }

    /**
     * 生成接口信息，包括标题、联系人等
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("如有疑问，可联系二师兄，微信：zhuan2quan")
                .contact(new Contact("二师兄", "https://www.choupangxia.com/", "secbro2@gmail.com"))
                .version("1.0")
                .build();
    }

    /**
     * 封装全局通用参数
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("uuid")
                .description("设备uuid")
                .required(true)
                .in(ParameterType.QUERY)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }

    /**
     * 封装通用响应信息
     */
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("未找到资源").build());
        return responseList;
    }
}

С помощью приведенной выше конфигурации интеграция Spring Boot и Swagger завершена.Ниже показано, как использовать ее в бизнес-логике.

использовать в бизнесе

Создайте два класса сущностей Goods (класс товаров) и CommonResult (общий класс результатов возврата).

Класс товара:

@ApiModel("商品模型")
public class Goods {

    /**
     * 商品id
     */
    @ApiModelProperty("商品ID")
    Long goodsId;

    /**
     * 商品名称
     */
    @ApiModelProperty("商品名称")
    private String goodsName;

    /**
     * 商品价格
     */
    @ApiModelProperty("商品价格")
    private BigDecimal price;

    // 省略getter/setter
}

Класс CommonResult:

@ApiModel("API通用数据")
public class CommonResult<T> {

    /**
     * 标识代码，0表示成功，非0表示出错
     */
    @ApiModelProperty("标识代码,0表示成功，非0表示出错")
    private Integer code;

    /**
     * 描述信息，通常错时使用
     */
    @ApiModelProperty("错误描述")
    private String msg;

    /**
     * 业务数据
     */
    @ApiModelProperty("业务数据")
    private T data;

    public CommonResult(Integer status, String msg, T data) {
        this.code = status;
        this.msg = msg;
        this.data = data;
    }

    /**
     * 成功
     */
    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<>(0, "成功", data);
    }

    public static <T> CommonResult<T> success(Integer code, String msg) {
        return new CommonResult<>(code, msg, null);
    }

    /**
     * 错误
     */
    public static <T> CommonResult<T> error(int code, String msg) {
        return new CommonResult<>(code, msg, null);
    }

    // 省略getter/setter
}

Ниже используется API, соответствующий Swagger, для интерфейса уровня контроллера.

Класс GoodsController:

@Api(tags = "商品信息管理接口")
@RestController
@RequestMapping("/goods")
public class GoodsController {

    @Operation(summary = "单个商品详情")
    @GetMapping("/findGoodsById")
    public CommonResult<Goods> findGoodsById(
            @Parameter(description = "商品ID,正整数")
            @RequestParam(value = "goodsId", required = false, defaultValue = "0") Integer goodsId) {
        System.out.println("根据商品ID=" + goodsId + "查询商品详情");
        Goods goods = new Goods();
        goods.setGoodsId(1L);
        goods.setGoodsName("笔记本");
        goods.setPrice(new BigDecimal(8888));
        return CommonResult.success(goods);
    }
}

Класс контроллера заказа:

@Api(tags = "订单管理接口")
@RestController
@RequestMapping("/order")
public class OrderController {

    @Operation(summary = "提交订单")
    @PostMapping("/order")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户id", dataTypeClass = Long.class, paramType = "query", example = "123"),
            @ApiImplicitParam(name = "goodsId", value = "商品id", dataTypeClass = Integer.class, paramType = "query", example = "1")
    })
    public CommonResult<String> toBuy(@ApiIgnore @RequestParam Map<String, String> params) {
        System.out.println(params);
        return CommonResult.success("success");
    }
}

Отображение результатов

Завершите интеграцию, запустите проект SpringBoot по адресу доступа:

http://127.0.0.1:8080/swagger-ui/index.html

В целом можно наблюдать следующие эффекты:swagger

Для интерфейса управления информацией о конкретном товаре вы можете увидеть параметры запроса, структуру данных возвращаемого результата и другую информацию, нажать «Попробовать», вы можете ввести параметры запроса параметров и вызвать интерфейс:swagger

После вызова будет возвращен соответствующий результат обработки:

swagger

В нижних схемах вы также можете увидеть соответствующие возвращенные данные результата и информацию о классе сущностей, аннотированную Swagger.

swagger

Инструкции по аннотации Swagger3

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

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

Экспорт автономных документов

Swagger предоставляет нам удобную онлайн-поддержку документации, но в некоторых сценариях нам нужно предоставить документацию по интерфейсу соавторам, а не указывать адрес напрямую. На этом этапе нам нужно экспортировать документ интерфейса как автономный документ.

Здесь мы интегрируем расширенный документ knife4j для экспорта автономных документов.

Добавить зависимость knife4j

Добавьте зависимость knife4j в pom.xml:

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

начать нож4j

Добавьте аннотацию @EnableKnife4j в Swagger3Config, который настраивает Swagger выше, что позволяет улучшить knife4j.

@EnableKnife4j
@Configuration
@EnableOpenApi
public class Swagger3Config {
    // ...
}

На данный момент, если вы все еще посещаетеhttp://localhost:8080/swagger-ui/index.htmlВы обнаружите, что дисплей не изменился. Здесь нам нужно получить доступhttp://локальный:8088/doc.html.

Адрес исходного кода всего проекта:GitHub.com/Цвета не так хороши/Судный день…

Отображение результатов

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

swagger

swagger

swagger

swagger

Среди них в столбце «Офлайн-документ» можно увидеть четыре формы загрузки офлайн-документа: Markdown, HTML, Word, OpenAPI.

swagger-09.jpg

Среди них я лично считаю, что документы в формате HTML более смелые и их легче просматривать.Давайте сделаем снимок, чтобы увидеть эффект.

swagger-10.jpg

резюме

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

Открывайте для себя что-то новое и пробуйте новое, чтобы расти быстрее и иметь больше плана Б.

Профиль блоггера: автор технической книги SpringBoot Technology Insider, который любит изучать технологии и писать технические статьи.

Публичный аккаунт: "Новые горизонты программ", публичный аккаунт блогера, прошу обратить внимание~

Технический обмен: пожалуйста, свяжитесь с блогером WeChat ID: zhuan2quan

Категории