В современной веб-разработке документация по API стала неотъемлемой частью. Swagger — это широко используемый инструмент документации API, который может помочь нам создавать документацию API, которая легко читается и тестируется. Весной В проекте Boot документацию по API можно легко создать путем интеграции Swagger. В этой статье речь пойдет о Группировке. интерфейса Проблемы Swagger и сегментации, а также обсуждение их применения в реальной разработке.

Введение в Swagger

Swagger — это инструмент документации RESTful API, который может автоматически создавать документацию на основе кода API. Swagger поддерживает несколько языков программирования и платформ, включая Java, Python, PHP и т. д., а также поддерживает несколько форматов вывода, таких как JSON, YAML и XML.

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

Группировка интерфейса Swagger

В проектах Spring Boot контроллеры обычно имеют несколько интерфейсов. Эти интерфейсы могут принадлежать разным функциональным модулям или разным версиям, и их необходимо классифицировать и классифицировать. Swagger предоставляет функцию группировки интерфейсов, которая позволяет группировать интерфейсы по разным категориям и отображать их в документе.

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

В проекте Spring Boot мы можем определить группы интерфейсов с помощью аннотации Swagger @Api. Например:

@RestController
@RequestMapping("/users")
@Api(tags = «Управление пользователями»)
public class UserController {
    // ...
}

В приведенном выше коде аннотация @Api указывает метку контроллера как «Управление пользователями», и эта метка будет использоваться в качестве имени группы интерфейсов.

Расширенное использование

Если контроллер содержит несколько интерфейсов, представление и описание каждого интерфейса можно указать с помощью аннотации @ApiOperation. Например:

@RestController
@RequestMapping("/users")
@Api(tags = «Управление пользователями»)
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = «Получить информацию о пользователе», notes = «Получить информацию о пользователе на основе идентификатора пользователя»)
    public User getUserById(@PathVariable("id") Long id) {
        // ...
    }

    @PostMapping
    @ApiOperation(value = «Создать пользователя», notes = «Создать нового пользователя»)
    public User createUser(@RequestBody User user) {
        // ...
    }

    // ...
}

В приведенном выше коде аннотация @ApiOperation указывает имя и описание каждого интерфейса. Эта информация будет отображаться в документе Swagger.

Сортировка интерфейса Swagger

В документации Swagger,Порядок интерфейсов очень важен. Определяет порядок отображения интерфейса,Для разработчиков и тестировщиков,это очень важно。SwaggerДва типа Метод сортировки интерфейса：Сортировать по имени метода интерфейсаи Сортировать по пути запроса интерфейса。

Сортировать по имени метода интерфейса

По умолчанию Swagger сортирует имена методов интерфейса в алфавитном порядке. Например, в следующем коде метод getUserById будет поставлен в очередь перед методом createUser:

@RestController
@RequestMapping("/users")
@Api(tags = «Управление пользователями»)
public class UserController {

    @GetMapping("/{id}")
    public User getUserById(@PathVariable("id") Long id) {
        // ...
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        // ...
    }

    // ...
}

Сортировать по пути запроса интерфейса

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

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build()
                .directModelSubstitute
                (Long.class, Integer.class)
                .apiInfo(apiInfo())
                .tags(new Тег("Управление пользователями", "Интерфейс управления пользователями"))
                .enable(true)
                .groupName("user") // Имя группы интерфейсов
                .order(Ordering.byPath()); // Метод сортировки интерфейса
    }
}

В приведенном выше коде,Мы добавили метод .order(), чтобы указать, как упорядочивается интерфейс. Здесь используется метод Ordering.byPath().,выражать Сортировать по пути запроса интерфейса。

Сегментация интерфейса

Если контроллер содержит большое количество интерфейсов, возможно, его необходимо классифицировать и классифицировать более подробно. Swagger также предоставляет аннотации @ApiOperation и @ApiImplicitParam, которые позволяют более детально разделить интерфейс.

Например, в следующем коде мы используем аннотацию @ApiOperation для указания введения и описания каждого интерфейса, а также аннотацию @ApiImplicitParam для указания имени, типа и описания каждого параметра:

@RestController
@RequestMapping("/users")
@Api(tags = «Управление пользователями»)
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = «Получить информацию о пользователе», notes = «Получить информацию о пользователе на основе идентификатора пользователя»)
    @ApiImplicitParam(name = "id", value = "ID пользователя", required = true, dataType = "Long", paramType = "path")
    public User getUserById(@PathVariable("id") Long id) {
        // ...
    }

    @PostMapping
    @ApiOperation(value = «Создать пользователя», notes = «Создать нового пользователя»)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = «Пользователь», required = true, dataType = "User", paramType = "body")
    })
    public User createUser(@RequestBody User user) {
        // ...
    }

    // ...
}

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

Подвести итог

Весной В проекте Boot Swagger — очень удобный инструмент документации API. Используя Swagger, мы можем легко создавать документацию по API и реализовывать группировку и сортировку интерфейсов. Группировка и порядок интерфейсов очень важны для читаемости и тестируемости документов API, поэтому нам необходимо сделать разумные настройки, исходя из реальных потребностей. В то же время Сегментация интерфейса – тоже важный вопрос,При написании документации API,Нам необходимо как можно более подробно различать различные интерфейсы и параметры.,Чтобы помочь разработчикам лучше понять и использовать API.