Документация Java REST API с помощью Swagger 2

Вступление

В этой статье мы погрузимся в структуру Swagger . Мы будем использовать Swagger 2 для проектирования, сборки и документирования Spring Boot RESTful API и Swagger UI для наблюдения за нашими конечными точками и их тестирования.

Что такое Суэггер?

Swagger-наиболее широко используемый инструмент для создания API, совместимых со спецификацией Open API (OAS).

Swagger сам по себе представляет собой набор инструментов с открытым исходным кодом, созданных по всему ДОМУ, которые могут помочь вам разрабатывать, создавать, документировать и генерировать документы REST API для веб-сервисов RESTful.

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

Редактор Swagger – редактор на основе браузера, в котором вы можете писать спецификации OpenAPI
Пользовательский интерфейс Swagger – отображает спецификации OpenAPI в виде интерактивной документации API
Swagger Codegen – генерирует заглушки сервера и клиентские библиотеки из спецификации OpenAPI

Swagger 2 является расширением Swagger в новые технологии и протоколы, выходящие за рамки HTTP .

Создание приложения

Интеграция Swagger 2 в приложение Spring Boot происходит довольно быстро и легко с помощью некоторых инструментов, которые мы уже используем изо дня в день.

Самый простой способ начать с проекта загрузки со скелетной пружиной, как всегда, – использовать href=” https://start.spring.io/”>Инициализация Весны. href=” https://start.spring.io/”>Инициализация Весны.

Выберите предпочитаемую версию Spring Boot и сгенерируйте ее как проект Maven, и все готово!

Чтобы включить Swagger 2 самостоятельно, вам нужно будет добавить пару зависимостей к вашему pom.xml файл:


    io.springfox
    springfox-swagger2
    ${version}

После полной настройки нашего проекта и проверки наших зависимостей мы можем продолжить и создать простую конечную точку REST, которую мы представим в документации позже:

@RestController
@RequestMapping("/v1/hello")
public class HelloResource {

    @GetMapping
    public String hello() {
        return "Hello World";
    }

    @PostMapping("/post")
    public String helloPost(@RequestBody String hello) {
        return hello;
    }

    @PutMapping("/put")
    public String helloPut(@RequestBody String hello) {
        return hello;
    }
}

После этого давайте продолжим и создадим еще одну конечную точку REST – Пользовательский ресурс :

@RestController
@RequestMapping("/v1/user")
public class UserResource {

@GetMapping
public List getUsers() {
    return Arrays.asList(
        new User("John", 3000),
        new User("Kevin", 2000)
    );
}

@GetMapping("/{userName}")
public User getUser(@PathVariable("userName") String userName) {
    return new User(userName, 2000);
}

Оба этих класса зависят от пользователя модели:

private class User {

    private String userName;
    private Integer salary;

    // constructor, getters and setters
}

Включение Swagger2

Сейчас самое время включить Wagger2 в нашем приложении, определив для него класс конфигурации.

Класс конфигурации должен быть аннотирован @Configuration – стандартной аннотацией Spring и @EnableSwagger2 аннотациями, чтобы включить платформу для вашего приложения Spring Boot.

Порядок этих аннотаций не важен:

@EnableSwagger2
@Configuration
public class Swagger2Config {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.demo.resource"))
            .paths(regex("/v1.*"))
            .build();
    }
}

Для этой цели мы определим Компонент с именем Список в классе конфигурации.

Docket -это конструктор, который предназначен для использования в качестве основного интерфейса в фреймворке swagger-springmvc . Он обеспечивает разумные значения по умолчанию и удобные методы настройки.

После определения компонента Docket вызов его метода select() возвращает экземпляр Api Selector Builder , который обеспечивает контроль над конечными точками , предоставляемыми Swagger.

Мы также можем определить базовый пакет для наших классов API REST, если захотим, используя Селекторы обработчиков запросов.базовый пакет() . Он будет сканировать базовый пакет и создавать API-интерфейсы для всех классов в нем.

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

В нашем случае это пакет com.demo.resource , в котором мы определили классы Приветственный ресурс и Пользовательский ресурс .

Метод paths() дополнительно определяет, для каких путей в наших API мы хотим создать документацию. Все наши конечные точки имеют “/v1”, поэтому в нашем случае он включает в себя все конечные точки. Однако это может быть не всегда так.

Если вы хотите включить все конечные точки – вы можете легко сделать это с помощью Селекторов путей.any() .

Пользовательский интерфейс Swagger

Давайте использовать Swagger UI для наблюдения за всеми нашими конечными точками REST, созданными Swagger.

Чтобы использовать пользовательский интерфейс Swagger, нам нужно добавить зависимость для него в ваш pom.xml файл:


    io.springfox
    springfox-swagger-ui
    ${version}

Git Essentials

Ознакомьтесь с этим практическим руководством по изучению Git, содержащим лучшие практики и принятые в отрасли стандарты. Прекратите гуглить команды Git и на самом деле изучите это!

Теперь перейдите к localhost:8080/swagger-ui.html . Это URL-адрес, по которому мы можем наблюдать все конечные точки rest, созданные Swagger:

Как вы можете видеть, обе наши конечные точки находятся здесь – привет-ресурс и пользовательский ресурс, с соответствующими методами внутри. Имена методов определены справа, как вы можете видеть.

Мы можем использовать этот пользовательский интерфейс для тестирования наших конечных точек:

Нажмите на Привет ресурс и разверните GET/v1/привет
Нажмите кнопку rest call Попробуйте кнопку

Нас встретит тело ответа “Привет, мир” и код ответа 200, что означает, что он работает так, как задумано.

То же самое, что и для GET/v1/пользователя из класса UserResource :

Нас встретят информацией, относящейся к пользователю, которого мы создали ранее.

Настройка Swagger2

Иногда компаниям и командам необходимо настраивать поведение Swagger 2, добавляя пользовательские сообщения и операции, чтобы адаптировать использование платформы к своим собственным потребностям.

Для этого нам нужно переопределить метаданные фреймворка с помощью Api Info .

Конструктор Epi info ожидает:

Заголовок строки
Описание строки
Строковая версия
Строка termsOfServiceUrl
новый контакт(имя контакта, "", "")
Лицензия на строку
Лицензиар строки

Если вы не хотите определять что-либо из этого, вы можете просто ввести null , и это поле не будет отображаться в пользовательском интерфейсе:

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.demo.resource"))
            .paths(regex("/v1.*"))
            .build()
            .apiInfo(metaInfo());
    }

    private ApiInfo metaInfo() {

        ApiInfo apiInfo = new ApiInfo(
            "Spring Boot Swagger2 Example API",
            null,
            "1.0",
            "Terms of Service",
            new Contact("Your Name or Team", null,
                null),
            "Apache License Version 2.0",
            "https://www.apache.org/licenses/"
        );

        return apiInfo;
    }
}

Мы можем переопределять имена методов с помощью аннотаций.

Аннотация @ApiOperation позволяет нам переопределить конечную точку и ее тип ответа. Swagger 2 также позволяет переопределять ответные сообщения по умолчанию методов HTTP|/.

Вы можете использовать аннотацию @ApiResponse для документирования других ответов в дополнение к обычному HTTP 200 OK :

@ApiOperation(value = "Returns Hello World", description = "shows hello world")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "The request has succeeded or (your message)"),
        @ApiResponse(code = 401, message = "The request requires user authentication or (your message)"),
        @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden or (your message)"),
        @ApiResponse(code = 404, message = "The server has not found anything matching the Request-URI or (your message)")

Давайте взглянем на пользовательский интерфейс:

При расширении привет-ресурс мы видим, что правая часть документации обновилась. Кроме того, в ответных сообщениях обновлен предоставленный нами код и возвращаемый тип из аннотации @Api на уровне класса.

Свойства модели

Swagger2 предоставляет нам набор аннотаций для управления моделями с большим контролем:

@ApiModel – Позволяет нам манипулировать метаданными модели
@ApiModelProperty – Позволяет нам контролировать определения и операции, специфичные для Swagger (допустимые значения, примечания, фильтрация)

Нам нужно будет обновить наш Пользовательский ресурс контроллер аннотацией @Api на уровне класса.

В Swagger 2 эта аннотация используется для применения определений ко всем операциям, определенным в ней, в отличие от ее использования в предыдущих версиях, где она объявляла ресурсы:

@RestController
@RequestMapping("/v1/user")
@Api(value = "User Resource REST Endpoint", description = "Shows the user info")
public class UserResource {

    @GetMapping
    public List getUsers() {

        return Arrays.asList(
            new User("John", 2000),
            new User("Kevin", 1000)
        );
    }

    @GetMapping("/{userName}")
    public User getUser(@PathVariable("userName") String userName) {
        return new User(userName, 1000);
    }

После обновления API давайте обновим и модель:

@ApiModel
private class User {

    @ApiModelProperty(notes = "name of the user")
    private String userName;

    @ApiModelProperty(notes = "salary of the user")
    private Integer salary;

    @ApiModelProperty(allowableValues = "active, inactive, banned")
    private String status;

    // constructor, getters and setters
}

Существует широкий спектр вещей, которые вы можете определить с помощью @ApiModelProperty . Для получения дополнительной информации и списка методов посетите официальную документацию .

Развернув GET/v1/user , затем щелкнув по свойству Модель , мы можем заметить описания в каждом поле.

“Пример значения” показывает только значения по умолчанию.

Вывод

Каждый день компании и частные лица начинают использовать Swagger в качестве предпочтительного инструмента для предоставления API REST третьим лицам.

Используя инструменты Swagger, вы можете создавать код на основе документации API, а также создавать красивую интерактивную документацию. Это одновременно экономит время и усилия и обеспечивает стандарт для людей, с которыми можно работать.