Статьи

Интеграция Swagger с REST API Spring Boot

Октябрь 30, 2018

В последнем посте я рассказал о своем опыте создания RESTFul Services с использованием Spring Boot . При создании REST API надлежащая документация является обязательной частью.

Что такое Swagger?

Swagger (Swagger 2) — это спецификация для описания и документирования REST API. Он определяет формат веб-сервисов REST, включая URL, ресурсы, методы и т. Д. Swagger будет генерировать документацию из кода приложения и обрабатывать также часть рендеринга.

В этой статье я собираюсь интегрировать документацию Swagger 2 в веб-сервис REST на основе Spring Boot. Поэтому я собираюсь использовать реализацию Springfox для генерации документации. Если вы хотите узнать, как запустить / собрать проект Spring Boot, обратитесь к моему предыдущему посту.

Springfox предоставляет две зависимости для генерации API Doc и Swagger UI. Если вы не планируете интегрировать Swagger UI в свой уровень API, нет необходимости добавлять зависимость Swagger UI.

1
2
3
4
5
6
7
8
9
<dependency>
 
<groupId>io.springfox</groupId>
 
<artifactId>springfox-swagger2</artifactId>
 
<version>2.7.0</version>
 
</dependency>
1
2
3
4
5
6
7
8
9
<dependency>
 
<groupId>io.springfox</groupId>
 
<artifactId>springfox-swagger-ui</artifactId>
 
<version>2.7.0</version>
 
</dependency>

@ Аннотация EnableSwagger2 включает поддержку Springfox Swagger в классе. Для документирования сервиса Springfox использует Docket. Docket помогает настроить подмножество сервисов, которые будут документированы, и сгруппировать их по имени и т. Д. Наиболее скрытая концепция заключается в том, что Springfox работает, исследуя приложение во время выполнения, используя семантику API на основе конфигураций Spring. Другими словами, вы должны создать класс Spring Spring Configuration, который использует @Configuration в Spring.

В моем примере я генерирую документацию swagger на основе классов RestController, которые я добавил.

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class ApplicationConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
}

Поскольку я добавил два контроллера, это сгруппирует (пометит) каждый API, связанный с контроллером, отдельно.

Из коробки Springfox предоставляет пять предикатов, и они являются любыми, ни с одним, с ClassAnnotation, withMethodAnnotation и basePackage.

ApiInfo

Swagger предоставляет некоторые значения по умолчанию, такие как «Документация API», «Создано контактной электронной почтой», «Apache 2.0». Таким образом, вы можете изменить эти значения по умолчанию, добавив метод apiInfo (ApiInfo apiInfo). Класс ApiInfo содержит пользовательскую информацию об API.

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
@Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "[email protected]");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }

После добавления ApiInfo сгенерированная документация выглядит примерно так:

Контроллер и документация уровня POJO

Аннотация @Api используется для объяснения каждого класса контроллера покоя.

Аннотация @ApiOperation используется для объяснения описания ресурсов и методов.

Аннотация @ApiResponse используется для пояснения, чтобы описать другие ответы, которые могут быть возвращены операцией. Например: 200 ok или 202 приняты и т. Д.

@ApiModelProperty аннотация для описания свойств класса POJO (Bean).

После добавления вышеприведенной аннотации окончательно сгенерированная документация по swagger выглядит так:

Класс Spring RestController:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
package com.chandana.helloworld.controllers;
 
import com.chandana.helloworld.bean.Greeting;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
@RequestMapping("/api")
@Api(value = "user", description = "Rest API for user operations", tags = "User API")
public class HelloWorldController {
 
    @RequestMapping(value = "/hello/{name}", method = RequestMethod.GET, produces = "application/json")
    @ApiOperation(value = "Display greeting message to non-admin user", response = Greeting.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK"),
            @ApiResponse(code = 404, message = "The resource not found")
    }
    )
    public Greeting message(@PathVariable String name) {
        Greeting msg = new Greeting(name, "Hello " + name);
        return msg;
    }
}

Приветствие модели класса:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
package com.chandana.helloworld.bean;
 
import io.swagger.annotations.ApiModelProperty;
 
public class Greeting {
 
    @ApiModelProperty(notes = "Provided user name", required =true)
    private String player;
 
    @ApiModelProperty(notes = "The system generated greeting message" , readOnly =true)
    private String message;
 
    public Greeting(String player, String message) {
        this.player = player;
        this.message = message;
    }
 
    public String getPlayer() {
        return player;
    }
 
    public void setPlayer(String player) {
        this.player = player;
    }
 
    public String getMessage() {
        return message;
    }
 
    public void setMessage(String message) {
        this.message = message;
    }
}

Класс AppConfig:

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
package com.chandana.helloworld.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class ApplicationConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chandana.helloworld.controllers"))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo getApiInfo() {
        Contact contact = new Contact("Chandana Napagoda", "http://blog.napagoda.com", "[email protected]");
        return new ApiInfoBuilder()
                .title("Example Api Title")
                .description("Example Api Definition")
                .version("1.0.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .contact(contact)
                .build();
    }
}

Вы также можете скачать исходный код Swagger Spring Boot Project из моего репозитория GitHub.

Ссылка: Интеграция Swagger с REST API Spring Boot от нашего партнера JCG
318
Share: