TOC

Настройка Swagger 2 с помощью Spring REST API

Настройка Swagger 2 с помощью Spring REST API

1. обзор

При создании REST API хорошая документация играет важную роль.

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

В этом руководстве мы рассмотримSwagger 2 for a Spring REST web service.. В этой статье мы будем использовать реализациюSpringfox спецификации Swagger 2.

Если вы не знакомы с Swagger, вам следует посетитьits web page, чтобы узнать больше, прежде чем продолжить эту статью.

Дальнейшее чтение:

Создать REST-клиент Spring Boot с помощью Swagger

Узнайте, как можно создать REST-клиент Spring Boot с помощью генератора кода Swagger.

Read more →

Введение в Spring REST Docs

В этой статье представлен Spring REST Docs, механизм, управляемый тестами, для создания документации для сервисов RESTful, которая является точной и удобочитаемой.

Read more →

Введение в Asciidoctor в Java

Узнайте, как создавать документы с помощью AsciiDoctor.

Read more →

2. Целевой проект

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

3. Добавление зависимости Maven

Как уже упоминалось выше, мы будем использовать реализацию Swagger в Springfox. Последнюю версию можно найтиon Maven Central.

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


    io.springfox
    springfox-swagger2
    2.9.2

4. Интеграция Swagger 2 в проект

4.1. Конфигурация Java

Конфигурация Swagger в основном сосредоточена вокруг bean-компонентаDocket. 

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
          .select()
          .apis(RequestHandlerSelectors.any())
          .paths(PathSelectors.any())
          .build();
    }
}

Swagger 2 включается с помощью аннотации@EnableSwagger2.

После определения bean-компонентаDocket его методselect() возвращает экземплярApiSelectorBuilder, который обеспечивает способ управления конечными точками, предоставляемыми Swagger.

Предикаты для выбораRequestHandlers могут быть настроены с помощьюRequestHandlerSelectors иPathSelectors. Использованиеany() для обоих сделает документацию для всего вашего API доступной через Swagger.

This configuration is enough to integrate Swagger 2 into an existing Spring Boot project. Для других проектов Spring требуется некоторая дополнительная настройка.

4.2. Конфигурация без загрузки Spring

Без Spring Boot у вас не будет роскоши автоматической настройки обработчиков ресурсов. Пользовательский интерфейс Swagger добавляет набор ресурсов, которые вы должны настроить как часть класса, который расширяетWebMvcConfigurerAdapter, и аннотируется@EnableWebMvc. 

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");

    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

4.3. верификация

Чтобы убедиться, что Springfox работает, вы можете посетить следующий URL в вашем браузере:

http://localhost:8080/spring-security-rest/api/v2/api-docs

В результате получается JSON-ответ с большим количеством пар ключ-значение, который не очень понятен человеку. К счастью, Swagger предоставляет для этой целиSwagger UI.

5. Swagger UI

Swagger UI - это встроенное решение, которое значительно упрощает взаимодействие пользователя с созданной Swagger документацией API.

5.1. Включение пользовательского интерфейса Swagger в Springfox

Для использования Swagger UI требуется еще одна зависимость Maven: 


    io.springfox
    springfox-swagger-ui
    2.9.2

Теперь вы можете протестировать его в своем браузере, посетивhttp://localhost:8080/your-app-root/swagger-ui.html

In our case, by the way, the exact URL will be:http://localhost:8080/spring-security-rest/api/swagger-ui.html

Результат должен выглядеть примерно так:

Screenshot_1

5.2. Изучение документации Swagger

В ответе Swagger естьlist of all controllers, определенный в вашем приложении. При нажатии на любой из них будут перечислены допустимые методы HTTP (DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUTс).

Расширение каждого метода предоставляет дополнительные полезные данные, такие как статус ответа, тип содержимого и список параметров. Также можно попробовать каждый метод, используя пользовательский интерфейс.

Способность Swagger синхронизироваться с вашей базой кода имеет решающее значение. Чтобы продемонстрировать это, вы можете добавить новый контроллер в ваше приложение. 

@RestController
public class CustomController {

    @RequestMapping(value = "/custom", method = RequestMethod.POST)
    public String custom() {
        return "custom";
    }
}

Теперь, если вы обновите документацию Swagger, вы увидитеcustom-controller в списке контроллеров. Как вы знаете, в ответе Swagger показан только один метод (POST).

6. Расширенная настройка

КомпонентDocket вашего приложения может быть настроен для предоставления вам большего контроля над процессом создания документации API.

6.1. API фильтрации для ответа Swagger

Не всегда желательно выставлять документацию для всего вашего API. Вы можете ограничить ответ Swagger, передав параметры в методыapis() иpaths() классаDocket.

Как видно выше,RequestHandlerSelectors позволяет использовать предикатыany илиnone, но также может использоваться для фильтрации API в соответствии с базовым пакетом, аннотациями класса и аннотациями методов.

PathSelectors обеспечивает дополнительную фильтрацию с помощью предикатов, которые сканируют пути запроса вашего приложения. Вы можете использоватьany(),none(),regex() илиant().

В приведенном ниже примере мы проинструктируем Swagger включать только контроллеры из определенного пакета с определенными путями, используя предикатant(). 

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("org.example.web.controller"))
      .paths(PathSelectors.ant("/foos/*"))
      .build();
}

6.2. Пользовательская информация

Swagger также предоставляет некоторые значения по умолчанию в своем ответе, которые вы можете настроить, такие как «Документация Api», «Создано по электронной почте», «Apache 2.0».

Чтобы изменить эти значения, вы можете использовать методapiInfo(ApiInfo apiInfo). КлассApiInfo, содержащий настраиваемую информацию об API. 

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
      .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
      .paths(PathSelectors.ant("/foos/*"))
      .build()
      .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfo(
      "My REST API",
      "Some custom description of API.",
      "API TOS",
      "Terms of service",
      new Contact("John Doe", "www.example.com", "[email protected]"),
      "License of API", "API license URL", Collections.emptyList());
}

6.3. Ответные сообщения пользовательских методов

Swagger позволяет использовать отglobally overriding response messages of HTTP methods доDocket методglobalResponseMessage(). Во-первых, вы должны указать Swagger не использовать ответные сообщения по умолчанию.

Предположим, вы хотите переопределить ответные сообщения500 и403 для всех методовGET. Для этого необходимо добавить код в блок инициализацииDocket (исходный код исключен для ясности): 

.useDefaultResponseMessages(false)
.globalResponseMessage(RequestMethod.GET,
  newArrayList(new ResponseMessageBuilder()
    .code(500)
    .message("500 message")
    .responseModel(new ModelRef("Error"))
    .build(),
    new ResponseMessageBuilder()
      .code(403)
      .message("Forbidden!")
      .build()));

Screenshot_2

7. Пользовательский интерфейс Swagger с API, защищенным OAuth

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

Давайте посмотрим, как мы можем разрешить Swagger доступ к API, защищенному OAuth, используя в этом примере тип предоставления кода авторизации.

Мы настроим Swagger для доступа к нашему защищенному API, используя поддержкуSecurityScheme иSecurityContext: 

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2).select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .securitySchemes(Arrays.asList(securityScheme()))
        .securityContexts(Arrays.asList(securityContext()));
}

7.1. Конфигурация безопасности

Мы определим bean-компонентSecurityConfiguration в нашей конфигурации Swagger и установим некоторые значения по умолчанию: 

@Bean
public SecurityConfiguration security() {
    return SecurityConfigurationBuilder.builder()
        .clientId(CLIENT_ID)
        .clientSecret(CLIENT_SECRET)
        .scopeSeparator(" ")
        .useBasicAuthenticationWithAccessCodeGrant(true)
        .build();
}

7.2. SecuritySchemeс

Затем мы определим нашSecurityScheme; это используется для описания защиты нашего API (базовая аутентификация, OAuth2,…).

В нашем случае мы определим схему OAuth, используемую для защиты нашегоResource Server: 

private SecurityScheme securityScheme() {
    GrantType grantType = new AuthorizationCodeGrantBuilder()
        .tokenEndpoint(new TokenEndpoint(AUTH_SERVER + "/token", "oauthtoken"))
        .tokenRequestEndpoint(
          new TokenRequestEndpoint(AUTH_SERVER + "/authorize", CLIENT_ID, CLIENT_SECRET))
        .build();

    SecurityScheme oauth = new OAuthBuilder().name("spring_oauth")
        .grantTypes(Arrays.asList(grantType))
        .scopes(Arrays.asList(scopes()))
        .build();
    return oauth;
}

Обратите внимание, что мы использовали тип предоставления кода авторизации - для которого нам необходимо предоставить конечную точку токена и URL авторизации нашего сервера авторизации OAuth2.

И вот области, которые мы должны определить: 

private AuthorizationScope[] scopes() {
    AuthorizationScope[] scopes = {
      new AuthorizationScope("read", "for read operations"),
      new AuthorizationScope("write", "for write operations"),
      new AuthorizationScope("foo", "Access foo API") };
    return scopes;
}

Они синхронизируются с областями действия, которые мы фактически определили в нашем приложении для API/foos.

7.3. Контекст безопасности

Наконец, нам нужно определить контекст безопасности для нашего примера API: 

private SecurityContext securityContext() {
    return SecurityContext.builder()
      .securityReferences(
        Arrays.asList(new SecurityReference("spring_oauth", scopes())))
      .forPaths(PathSelectors.regex("/foos.*"))
      .build();
}

Обратите внимание, как имя, которое мы использовали здесь, в ссылке -spring_oauth - синхронизируется с именем, которое мы использовали ранее, вSecurityScheme.

7.4. Test

Хорошо, теперь, когда у нас все настроено и готово к работе, давайте взглянем на наш пользовательский интерфейс Swagger и попробуем получить доступ к Foo API:

Мы можем получить доступ к Swagger UI локально: 

http://localhost:8082/spring-security-oauth-resource/swagger-ui.html

Как мы видим, новая кнопка «Авторизовать» теперь существует благодаря нашим настройкам безопасности:

image

Когда мы нажимаем кнопку «Авторизовать», мы видим следующее всплывающее окно - чтобы авторизовать наш Swagger UI для доступа к защищенному API:

image

Обратите внимание, что:

  • Мы уже видим CLIENT_ID и CLIENT_SECRET - как мы предварительно настроили их ранее (но мы все еще можем их изменить)

  • Теперь мы можем выбрать нужные области

Вот как отмечены защищенные API:

image

И вот, наконец, мы можем поразить наш API!

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

8. Заключение

В этом руководстве мы настроили Swagger 2 для создания документации для Spring REST API. Мы также изучили способы визуализации и настройки вывода Swagger. И, наконец, мы рассмотрели простую конфигурацию OAuth для Swagger.

full implementation этого руководства можно найти вthe Github project - это проект на основе Eclipse, поэтому его должно быть легко импортировать и запускать как есть. Чтобы увидеть настройку в проекте загрузки, посмотритеthis GitHub module.

Для раздела OAuth код доступен в нашем репозиторииspring-security-oauth.

А если вы студентof REST With Spring, перейдите к Уроку 1 модуля 7, чтобы подробно изучить настройку Swagger с помощью Spring и Spring Boot.

Related