Базовое руководство по Spring Boot 2.x: создание надежной документации API с помощью Swagger2

Spring Boot

С ростом популярности архитектуры разделения интерфейсов и серверов и микросервисной архитектуры появляется все больше и больше сценариев, в которых мы используем Spring Boot для создания проектов RESTful API. Обычно один из наших RESTful API может обслуживать несколько разных разработчиков или групп разработчиков: разработка для IOS, разработка для Android, веб-разработка и даже другие серверные службы. Чтобы снизить стоимость частого общения с другими командами во время обычной разработки, традиционный подход заключается в создании документа RESTful API для записи всех деталей интерфейса, однако у этого подхода есть следующие проблемы:

  • Из-за многочисленных интерфейсов и сложных деталей (необходимо учитывать различные типы HTTP-запросов, информацию HTTP-заголовка, содержимое HTTP-запроса и т. д.) очень сложно создать этот документ с высоким качеством, а последующие жалобы бесконечны.
  • С течением времени документ интерфейса должен изменяться синхронно, когда реализация интерфейса постоянно изменяется, а документ и код находятся на двух разных носителях.Если нет строгого механизма управления, легко вызвать несогласованность.

Чтобы решить вышеуказанные проблемы, в этой статье будет представлен Swagger2, хороший партнер RESTful API, который можно легко интегрировать в Spring Boot и сотрудничать с программой Spring MVC для организации мощных документов RESTful API. Это может не только снизить рабочую нагрузку по созданию документов, но и интегрировать содержание описания в код реализации, чтобы можно было интегрировать документ обслуживания и модификацию кода, что позволяет нам легко изменять описание документа при изменении логики кода. Кроме того, Swagger2 также предоставляет мощную функцию тестирования страниц для отладки каждого RESTful API. Конкретный эффект показан на следующем рисунке:

Давайте представим это подробно, используя нашу собственную реализацию стартера для интеграции Swagger в Spring Boot. Github интеграционного проекта:GitHub.com/spring для AL…. Если вы находите его простым в использовании, добро пожаловать в Star, чтобы поддержать нас!

Готов к работе

Прежде всего, нам нужен проект RESTful API, реализованный Spring Boot, Если вы еще не делали такого рода контент, рекомендуется сначала прочитать предыдущий учебник:Базовое руководство по Spring Boot 2.x: создание RESTful API и модульное тестированиеПостроить один. Либо можно напрямую использовать образец в предыдущем туториале за основу, то есть в следующем складеchapter2-1проект:

Интегрировать Swagger2

Далее используем вышеуказанный складchapter2-1Интеграция проекта.

первый шаг: добавить зависимость swagger-spring-boot-starter

существуетpom.xmlДобавьте зависимости следующим образом:

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

второй шаг: добавить в основной класс приложения@EnableSwagger2DocПримечания, как следует

@EnableSwagger2Doc
@SpringBootApplication
public class Chapter22Application {

    public static void main(String[] args) {
        SpringApplication.run(Chapter22Application.class, args);
    }

}

третий шаг:application.propertiesНастройте содержимое, связанное с документом, в , например

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
swagger.contact.email=dyc87112@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**

Значение каждой конфигурации параметров следующее:

  • swagger.title:заглавие
  • swagger.description:описывать
  • swagger.version:Версия
  • swagger.license:лицензия
  • swagger.licenseUrl: URL-адрес лицензии
  • swagger.termsOfServiceUrl: URL-адрес условий использования
  • swagger.contact.name: ремонтник
  • swagger.contact.url: URL сопровождающего
  • swagger.contact.email: электронная почта сопровождающего
  • swagger.base-package: базовый пакет для сканирования swagger, по умолчанию: полное сканирование
  • swagger.base-path: Основные правила URL для обработки, по умолчанию: /**

Дополнительные инструкции по настройке можно найти в официальной инструкции:GitHub.com/spring для AL…

четвертый шаг: запустите приложение, посетите:http://localhost:8080/swagger-ui.html, вы можете увидеть следующую страницу документации интерфейса:

Добавить содержимое документа

После интеграции Swagger вhttp://localhost:8080/swagger-ui.htmlКак вы можете видеть на странице, описания каждого интерфейса также генерируются на английском языке или в соответствии с именами, определенными в коде. Это содержимое не является удобным для пользователя, поэтому нам нужно самим добавить некоторые инструкции, чтобы обогатить содержимое документа. Как показано ниже, мы проходим@Api,@ApiOperationАннотации для добавления описаний в API через@ApiImplicitParam,@ApiModel,@ApiModelPropertyАннотации для добавления описаний к параметрам.

Например следующий пример:

@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "/users")     // 通过这里配置使下面的映射都在/users下
public class UserController {

    // 创建线程安全的Map，模拟users信息的存储
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());

    @GetMapping("/")
    @ApiOperation(value = "获取用户列表")
    public List<User> getUserList() {
        List<User> r = new ArrayList<>(users.values());
        return r;
    }

    @PostMapping("/")
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    @PutMapping("/{id}")
    @ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "用户编号", required = true, example = "1")
    @ApiOperation(value = "更新用户详细信息", notes = "根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }

    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除对象")
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "success";
    }

}

@Data
@ApiModel(description="用户实体")
public class User {

    @ApiModelProperty("用户编号")
    private Long id;
    @ApiModelProperty("用户姓名")
    private String name;
    @ApiModelProperty("用户年龄")
    private Integer age;

}

После добавления приведенного выше кода запустите программу Spring Boot и получите доступ:http://localhost:8080/swagger-ui.html, вы можете увидеть следующий документ с китайскими описаниями (соответствие между каждой аннотацией и элементом документа отмечено для справки):

Доступ к документации по API и отладка

На запрошенной странице выше мы видим, что значение пользователя является полем ввода? Да, в дополнение к просмотру функций интерфейса, Swagger также предоставляет функции отладки и тестирования.Мы можем щелкнуть по схеме модели (желтая область: она указывает на структуру данных пользователя) в правой части рисунка выше, и тогда появится пользователь объект в шаблоне Value., нам нужно только немного изменить его, нажмите ниже“Try it out！”кнопка для завершения запроса вызова!

На этом этапе вы также можете проверить правильность предыдущего запроса POST с помощью нескольких запросов GET.

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

пример кода

Полный проект этой статьи можно посмотреть на следующем складеchapter2-2содержание:

Если вы считаете, что эта статья хороша, добро пожаловатьStarПоддержите, ваше внимание - движущая сила моего упорства!

Эта статья является оригиналом "Program Ape DD", впервые опубликованной по адресу: http://blog.didispace.com/spring-boot-learning-21-2-2/.

Добро пожаловать, чтобы обратить внимание на мой общедоступный номер: Programmer DD, получить эксклюзивные учебные ресурсы и ежедневный толчок галантерейных товаров. Если вас интересует мой рекомендуемый контент, вы также можете подписаться на мой блог:didispace.com

Категории