Введение в использование и аннотации Swagger

Swagger

вводить

Что такое чванство

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

эффект

  • Документация по интерфейсу автоматически генерируется онлайн
  • функциональный тест

Swagger — это группа проектов с открытым исходным кодом, основными из которых являются следующие:

  • Swagger-tools: Предоставляет различные инструменты для интеграции и взаимодействия со Swagger. Например, проверка схемы, преобразование документа Swagger 1.2 в документ Swagger 2.0 и другие функции.

  • Swagger-core: реализация Swagger для Java/Scala. Интеграция с JAX-RS (Jersey, Resteasy, CXF...), сервлетами и платформами Play.

  • Swagger-js: реализация Swagger для JavaScript.

  • Swagger-node-express: модуль Swagger, платформа веб-приложений Express для node.js.

  • Swagger-ui: независимая коллекция HTML, JS и CSS, которая может динамически генерировать элегантную документацию для Swagger-совместимых API.

  • Swagger-codegen: Движок, управляемый шаблонами, который генерирует код на стороне клиента на разных языках, анализируя пользовательские объявления ресурсов Swagger.

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

Интеграция Swagger в Spring будет использоватьspringfox-swagger, который объединяет использование Spring и Swagger

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${springfox.swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.swagger.version}</version>
</dependency>

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

Настройка Swagger в Spring

/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 或者通过 @Import 导入配置
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.turbo.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("")
                .termsOfServiceUrl("")
                .contact("zou", "", "zouxq412@foxmail.com")
                .version("1.0")
                .build();
    }
}

Аннотации API

@Api

Эта аннотация, используемая в классах, помечает контроллер (класс) как ресурс чванства (API). По умолчанию Swagger-Core сканирует и анализирует только классы с аннотациями @Api и автоматически игнорирует аннотации для других типов ресурсов (конечные точки JAX-RS, сервлеты и т. д.). Аннотация содержит следующие важные атрибуты

  • теги Метки группировки API. API с одинаковым тегом будут сгруппированы и отображены в одной группе.
  • ценность Если теги не определены, значение будет использоваться как теги API.
  • описание Подробное описание API, который больше не используется после версии 1.5.X,Но на самом деле обнаружено, что его все еще можно использовать в версии 2.0.0.

@ApiOperation

Описывает операцию или метод HTTP на указанном (маршрутизирующем) пути. Различные операции с одним и тем же путем группируются в один и тот же объект операции. Различные комбинации методов и путей HTTP-запроса составляют уникальную операцию. Свойства этой аннотации:

  • ценность Простое описание операции, длина 120 букв и 60 китайских иероглифов.
  • Примечания Подробное описание операции.
  • httpМетод Имя действия HTTP-запроса. Необязательные значения: «GET», «HEAD», «POST», «PUT», «DELETE», «OPTIONS» и «PATCH».
  • код По умолчанию 200, допустимые значения должны соответствовать стандартуHTTP Status Code Definitions.

@ApiImplicitParams

Используется в методах, аннотирует класс контейнера ApiImplicitParam и сохраняет его в массиве.

@ApiImplicitParam

Аннотируйте один параметр API. Хотя аннотация @ApiParam привязана к параметрам JAX-RS, аннотация @ApiImplicitParam может определять список параметров унифицированным способом, и это также единственный способ определить параметры в средах Servlet и не-JAX-RS. Обратите внимание, что аннотация @ApiImplicitParam должна быть включена в аннотацию @ApiImplicitParams. Можно установить следующие важные свойства параметра:

  • название имя параметра
  • ценность краткое описание параметра
  • обязательный Это обязательный параметр
  • тип данных 参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
  • paramtype. Входящий (запрос) тип параметра, необязательные значения являются путь, запрос, корпус, заголовок или форма.

@ApiParam

Добавлено описание метаинформации для параметров. Эту аннотацию можно использовать только в интегрированной среде JAX-RS 1.x/2.x. Основными его свойствами являются

  • обязательный Является ли это обязательным параметром, значение по умолчанию — false
  • ценность краткое описание параметра

@ApiResponses

Аннотация Класс-оболочка @ApiResponse, структура массива. Даже если вам нужно использовать аннотацию @ApiResponse, вам необходимо включить аннотацию @ApiResponse в аннотацию @ApiResponses.

@ApiResponse

Описывает возможные возвращаемые результаты операции. Эту аннотацию можно использовать для описания всех возможных кодов успеха и ошибок при выполнении запроса REST API. Вы можете использовать или не использовать эту аннотацию для описания возвращаемого типа операции, но возвращаемый тип успешной операции должен быть определен в @ApiOperation. Если API имеет разные типы возврата, вам необходимо определить возвращаемые значения отдельно и связать типы возврата. Но Swagger не поддерживает аннотации для одного и того же кода возврата и нескольких типов возврата. Примечание. Эта аннотация должна быть включена в аннотацию @ApiResponses.

  • код Код возврата HTTP-запроса. Допустимые значения должны соответствовать стандартуHTTP Status Code Definitions.
  • сообщение Более понятные текстовые сообщения
  • отклик Информация о типе возврата должна использовать полное имя класса, например "com.xyz.cc.Person.class".
  • ответконтейнер Если возвращаемый тип является типом контейнера, вы можете установить соответствующее значение. Допустимыми значениями являются «Список», «Набор» или «Карта», любые другие недопустимые значения игнорируются.

Аннотация модели

Для аннотаций модели Swagger предоставляет две: @ApiModel и @ApiModelProperty, которые используются для описания модели и свойств в модели соответственно.

@ApiModel

Опишите информацию модели (обычно используется, когда параметры запроса не могут быть описаны с помощью аннотации @ApiImplicitParam)

Предоставляет описание дополнительной информации о модели Swagger. В рамках операции, аннотированной аннотацией @ApiOperation, все классы будут автоматически подвергаться самоанализу, но эта аннотация позволяет более подробно описать структуру модели. Основные свойства:

  • ценность Псевдоним модели, по умолчанию это имя класса
  • описание Подробное описание модели

@ApiModelProperty

описать свойства модели

Для аннотации атрибута модели основными значениями атрибута являются:

  • ценность краткое описание недвижимости
  • пример пример значений для свойств
  • обязательный Это обязательное значение

Пример аннотации

Пример API

@AllArgsConstructor
@RestController
@RequestMapping("/api/category")
@Api(value = "/category", tags = "组件分类")
public class BizCategoryController {

    private IBizCategoryService bizCategoryService;

    @GetMapping("/list")
    @ApiOperation(value = "列表", notes = "分页列表")
    public R<PageModel<BizCategory>> list(PageQuery pageQuery,
                                          @RequestParam @ApiParam("组件分类名称") String name) {
        IPage<BizCategory> page = bizCategoryService.page(pageQuery.loadPage(),
                new LambdaQueryWrapper<BizCategory>().like(BizCategory::getName, name));
        return R.success(page);
    }

    @GetMapping("/list/all")
    @ApiOperation(value = "查询所有", notes = "分页列表")
    public R<List<BizCategory>> listAll() {
        List<BizCategory> categories = bizCategoryService.list();
        return R.success(categories);
    }

    @GetMapping("/{categoryId}")
    @ApiOperation(value = "详情", notes = "组件分类详情")
    public R<BizCategory> detail(@PathVariable @ApiParam("分类Id") Long categoryId) {
        BizCategory category = bizCategoryService.getById(categoryId);
        return R.success(category);
    }

    @PostMapping("/save")
    @ApiOperation(value = "保存", notes = "新增或修改")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "form", name = "categoryId", value = "组件id（修改时为必填）"),
            @ApiImplicitParam(paramType = "form", name = "name", value = "组件分类名称", required = true)
    })
    public R<BizCategory> save(Long categoryId, String name) {
        BizCategory category = new BizCategory();
        category.setId(categoryId);
        category.setName(name);
        bizCategoryService.saveOrUpdate(category);
        return R.success(category);
    }

    @DeleteMapping("/{categoryId}")
    @ApiOperation(value = "删除", notes = "删除")
    public R delete(@PathVariable @ApiParam("分类Id") Long categoryId) {
        bizCategoryService.delete(categoryId);
        return R.success();
    }
}

Пример апимодели

@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
@ApiModel(value="BizComponent对象", description="组件")
public class BizComponent implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    @ApiModelProperty(value = "分类")
    private Long categoryId;

    @ApiModelProperty(value = "组件名称")
    private String name;

    @ApiModelProperty(value = "组件描述")
    private String description;

    @ApiModelProperty(value = "日期字段")
    private LocalDateTime componentTime;

    @ApiModelProperty(value = "创建时间")
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    @ApiModelProperty(value = "修改时间")
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime modifiedTime;
}

интерфейс swagger-ui

Информационный интерфейс документа API, сгенерированный Swagger,/v2/api-docs, но мы можем использовать интерфейс пользовательского интерфейса, чтобы увидеть его более четкоДокументация, а также можетОнлайн-отладка

springfox-swagger-ui

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${springfox.swagger.version}</version>
</dependency>

при использованииspringfox-swagger-ui, путь доступа к документу API после запуска проекта — /swagger-ui.html

swagger-bootstrap-ui

swagger-bootstrap-uiЭто повышенная реализация UI SpringFox-Swagger. Я лично рекомендую использовать этот интерфейс. Структура документов API более понятна, а онлайн-отладку также очень удобна.

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>${swagger.bootstrap.ui.version}</version>
</dependency>

Посещенный URL-адрес/doc.html

Группировка чванства

Интерфейс группировки Swagger предназначен для настройки различных пакетов сканирования через серверную часть и ответа на внешний интерфейс в соответствии с основными свойствами настроенного пакета сканирования.

Конфигурация серверной Java выглядит следующим образом: указывается имя группы и пакет для сканирования.

@Bean(value = "defaultApi")
public Docket defaultApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("默认接口")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
        .paths(PathSelectors.any())
        .build();
}
@Bean(value = "groupApi")
public Docket groupRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(groupApiInfo())
        .groupName("分组接口")
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.example.demo.group"))
        .paths(PathSelectors.any())
        .build();
}

Интерфейс для группировки информации/swagger-resources

[
    {
        "name": "分组接口",
        "url": "/v2/api-docs?group=分组接口",
        "swaggerVersion": "2.0",
        "location": "/v2/api-docs?group=分组接口"
    },{
        "name": "默认接口",
        "url": "/v2/api-docs?group=默认接口",
        "swaggerVersion": "2.0",
        "location": "/v2/api-docs?group=默认接口"
    }
]

Вы также можете просмотреть документацию по API, сгруппировав в swagger-ui

Категории