SpringBoot интегрирует Swagger на практике

Spring Boot

Адрес источника:GitHub.com/lawrence/tickets…

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

Swagger действует на интерфейсы для визуализации данных интерфейса, особенно для Restful APi.

Этот раздел разделен на две части: первая часть — это два способа, которыми SpringBoot представляет Swagger, а вторая часть — подробное введение в применение аннотаций Swagger в веб-интерфейсе.

В этой статье используются SpringBoot 2.1.10.RELEASE и springfox-swagger 2.9.2.

1. Два способа для SpringBoot представить Swagger

В настоящее время SpringBoot имеет два способа использования Swagger:

  1. Внедрение нативных зависимостей swaggerspringfox-swagger2иspringfox-swagger2-ui
  2. Внедрить зависимости, разработанные внутренним сообществом Spring4All.swagger-spring-boot-starter

Зависимости, созданные Spring4All, настраиваются файлами конфигурации, а собственные зависимости устанавливаются классом конфигурации java.

1.1 Собственная конфигурация Swagger

maven-зависимости:

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
 	<version>2.9.2</version>
</dependency>

класс конфигурации чванства:

/**
 * swagger2配置类
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("基于Swagger构建的Rest API文档")
                .description("更多请咨询服务开发者eknown")
                .contact(new Contact("空夜", "http://www.eknown.cn", "eknown@163.com"))
                .termsOfServiceUrl("http://www.eknown.com")
                .version("1.0")
                .build();
    }
}

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

swagger-spring-boot-starter, созданный сообществом spring4all, может решить эту проблему.

1.2 Настройка swagger на основе spring4all

Блогеры сообщества Spring4All DD и Xiaohuo разработали Spring Boot Starter Swagger, который теперь доступен в официальном репозитории maven.

file

Выберите первый и импортируйте эту зависимость:

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

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

server:
  port: 8106
swagger:
  base-path: /**
  base-package: 'com.example'
  title: 'spring-boot-swagger-demo'
  description: '基于Swagger构建的SpringBoot RESTApi 文档'
  version: '1.0'
  contact:
    name: '空夜'
    url: 'http://www.eknown.cn'
    email: 'eknown@163.com'

Во-вторых, используйте Swagger для создания визуализации интерфейса.

2.1 Добавьте аннотацию Swagger в класс контроллера

Вот простой пример:

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "user")
public class UserController {

    // 模拟数据库存储的用户
    private static Map<Integer, User> userMap;

    static {
        userMap = new ConcurrentHashMap<>();
        User user = new User(0, "admin", true, new Date());
        userMap.put(user.getId(), user);
    }

    @ApiOperation("列表查询")
    @GetMapping(value = "")
    public List<User> list() {
        return new ArrayList<>(userMap.values());
    }

    @ApiOperation(value = "获取用户详细信息", notes = "路径参数ID")
    @GetMapping(value = "{id}")
    public User detail(@PathVariable Integer id) {
        return userMap.get(id);
    }

    @ApiOperation(value = "新增或更新用户信息", notes = "insert和update共用"
            , response = User.class)
    @PostMapping(value = "")
    public User add(@RequestBody User user) {
        if (user == null || user.getId() == null || !StringUtils.isEmpty(user.getName())
                || userMap.containsKey(user.getId())) {
            return null;
        }

        user.setUpdateTime(new Date());
        userMap.put(user.getId(), user);
        return user;
    }


    @ApiOperation(value = "删除用户")
    @DeleteMapping(value = "{id}")
    public Boolean delete(@ApiParam(name = "用户ID", required = true, example = "100") @PathVariable Integer id) {
        if (userMap.containsKey(id)) {
            userMap.remove(id);
            return true;
        }

        return false;
    }

}

2.2 Добавьте аннотацию Swagger в класс объекта параметра

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

@ApiModel(description = "用户类")
public class User {

    @ApiModelProperty(value = "ID", example = "100")
    private Integer id;

    @ApiModelProperty(value = "姓名", example = "laolunsi")
    private String name;

    @ApiModelProperty(value = "是否启用", example = "1")
    private Boolean enable;

    @ApiModelProperty("更新时间")
    private Date updateTime;

    public User(Integer id, String name, Boolean enable, Date updateTime) {
        this.id = id;
        this.name = name;
        this.enable = enable;
        this.updateTime = updateTime;
    }

    // ... ignore getter and setter methods
}

2.3 Тестирование

Запустите проект и посетите http://localhost:port/swagger-ui.html.

Если есть конфигурация server.servlet.context-path, адрес доступа будет http://localhost:port/context-path/swagger-ui.html.

file

Таким образом, интерфейс понятен с первого взгляда, а swagger также поддерживает онлайн-тестирование интерфейса, аналогично роли почтальона.

Что ж, пока что мы успешно интегрировали Swagger в проект SpringBoot, так что появился стандарт стыковки фронтенд- и бэкенд-разработки!

обмен обучением

Мой личный сайт:www.eknown.cn

Адрес Git-репозитория:github.com/laolunsi

Кроме того, вы также можете обратить внимание на мой публичный номер:обезьяний язык, изучайте технологии Java/SpringBoot/SpringCloud вместе.

Категории