Spring Boot (15): элегантное использование инструмента документации API Swagger2

Spring Boot

1. Введение

Вы наверняка сталкивались с опытом пыток интерфейсными документами в процессе разработки.Из-за легковесности и низкой связности RESTful интерфейсов мы не обновили вовремя документы после модификации интерфейса, в результате чего вызывающая сторона интерфейса( будь то front-end или back-end). ) часто жалуется, что интерфейс не соответствует документации. Характеристика программистов в том, что они не любят писать документацию, но в то же время не любят, когда другие не пишут документацию. Таким образом, в это время появился инструмент документации API.В этой статье мы представим инструмент документации API Swagger2.

2. Начните быстро

Поскольку Swagger2 — это инструмент документирования API, давайте посмотрим, как этот инструмент документирования используется в Spring Boot в коде.

2.1 Знакомство с зависимостями

Листинг кода: spring-boot-swagger/pom.xml***

<!-- swagger工具包 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

Здесь выбрана версия2.9.2, которая также является последней версией.

2.2 Класс конфигурации SwaggerConfig

Листинг кода: spring-boot-swagger/src/main/java/com/springboot/springbootswagger/config/SwaggerConfig.java***

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Value("${swagger.show}")
    private boolean swaggerShow;

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerShow)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.springboot.springbootswagger"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2 演示接口RESTful APIs")
                .version("1.0")
                .build();
    }
}

Поскольку Swagger — это инструмент документации API, мы не должны открывать его в рабочей среде, поэтому автор добавил его в конфигурацию.swagger.show, настраивать разные значения в конфигурационных файлах разных сред, или при наличии конфигурационного центра эту конфигурацию можно добавить в конфигурационный центр.Авторский пример здесь добавлен в конфигурационный файл приложения для простоты. Таким образом, мы можем изящно включить или отключить функциональность Swagger.

2.3 Класс объекта

Листинг кода: spring-boot-swagger/src/main/java/com/springboot/springbootswagger/model/User.java***

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户演示类", description = "请求参数类")
public class User {
    @ApiModelProperty(example = "1", notes = "用户ID")
    private Long id;
    @ApiModelProperty(example = "geekdigging", notes = "用户名")
    private String nickName;
    @ApiModelProperty(example = "1570689455000", notes = "创建时间")
    private Date createDate;
    @ApiModelProperty(example = "18", notes = "用户年龄")
    private Integer age;
}

Детали аннотации Swagger:

API Сфера используемое местоположение
@ApiModel Описать значение возвращаемого объекта Используется в возвращаемом классе объекта
@ApiModelProperty свойства объекта Используется в полях входящих и исходящих объектов параметров
@Api Описание набора протоколов для класса контроллера
@ApiOperation Описание протокола Используется в методах контроллера
@ApiResponses Набор ответов Используется в методах контроллера
@ApiResponse Response Используется в @ApiResponses
@ApiImplicitParams набор необъектных параметров Используется в методах контроллера
@ApiImplicitParam Описание параметра, не являющегося объектом Используется в методе @ApiImplicitParams

2.4 Controller

Листинг кода: spring-boot-swagger/src/main/java/com/springboot/springbootswagger/controller/UserController.java***

@Api(value = "用户管理演示")
@RestController
public class UserController {

    @Autowired
    UserService userService;

    @GetMapping("/getUserById/{id}")
    @ApiOperation(value = "获取用户信息", notes = "根据用户 id 获取用户信息", tags = "查询用户信息类")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }

    @GetMapping("/getAllUsers")
    @ApiOperation(value = "获取全部用户信息", notes = "获取全部用户信息", tags = "查询用户信息类")
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @PostMapping("/saveUser")
    @ApiOperation(value = "新增/修改用户信息")
    public User saveUser(@RequestBody User user) {
        return userService.saveUser(user);
    }

    @DeleteMapping("/deleteById")
    @ApiOperation(value = "删除用户信息", notes = "根据用户 id 删除用户信息")
    public String deleteById(@PathVariable Long id) {
        userService.deleteById(id);
        return "success";
    }
}

  • Тег тега в @ApiOperation можно использовать для группировки интерфейсов.

2.5 Результаты отображения следующие

Запустите проект, откройте браузер для посещения: http://localhost:8080/swagger-ui.html, вы увидите следующую страницу:

Мы можем видеть нашу группу тегов на этом изображении.

3. Пример кода

Пример кода — Гитхаб

Пример кода — Gitee

4. Ссылка

https://blog.csdn.net/xupeng874395012/article/details/68946676

Если моя статья была вам полезна, отсканируйте код и подпишитесь на официальный аккаунт автора: Получите последние новости о галантерейных товарах :)

Категории