1. Обзор
В этом руководстве мы увидим, как мы можем использовать аннотации Swagger, чтобы сделать нашу документацию более описательной. Мы узнаем, как добавить описание к различным частям API, таким как методы, параметры и коды ошибок. Мы также увидим, как добавить примеры запроса/ответа.
2. Настройка проекта
Мы создадим простой API продуктов, который предоставляет методы для создания и получения продуктов.
Чтобы создать REST API с нуля, мы можем следовать этому руководству из Spring Docs, чтобы создать веб-службу RESTful с использованием Spring Boot.
Следующим шагом будет настройка зависимостей и конфигураций для проекта. Мы можем выполнить шаги, описанные в этой статье , для настройки Swagger 2 с помощью Spring REST API.
3. Создание API
Сначала мы создадим наш API продуктов и проверим сгенерированную документацию.
3.1. Модель
Давайте определим наш класс Product :
public class Product implements Serializable {
private long id;
private String name;
private String price;
// constructor and getter/setters
}
3.2. Контроллер
Давайте определим два метода API:
@RestController
@ApiOperation("Products API")
public class ProductController {
@PostMapping("/products")
public ResponseEntity<Void> createProduct(@RequestBody Product product) {
//creation logic
return new ResponseEntity<>(HttpStatus.CREATED);
}
@GetMapping("/products/{id}")
public ResponseEntity<Product> getProduct(@PathVariable Long id) {
//retrieval logic
return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
}
}
Когда мы запустим проект, библиотека прочитает все открытые пути и создаст соответствующую им документацию.
Давайте просмотрим документацию по URL-адресу по умолчанию http://localhost:8080/swagger-ui/index.html :
Мы можем дополнительно расширить методы контроллера, чтобы посмотреть их соответствующую документацию. Далее мы рассмотрим их подробно.
4. Делаем нашу документацию описательной
Теперь давайте сделаем нашу документацию более описательной, добавив описания к различным частям методов.
4.1. Добавить описание к методам и параметрам
Давайте рассмотрим несколько способов сделать методы описательными. Мы добавим описания к методам, параметрам и кодам ответов. Начнем с метода getProduct() :
@ApiOperation(value = "Get a product by id", notes = "Returns a product as per the id")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successfully retrieved"),
@ApiResponse(code = 404, message = "Not found - The product was not found")
})
@GetMapping("/products/{id}")
public ResponseEntity<Product> getProduct(@PathVariable("id") @ApiParam(name = "id", value = "Product id", example = "1") Long id) {
//retrieval logic
return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
}
@ApiOperation определяет свойства метода API. Мы добавили имя операции с помощью свойства value и описание с помощью свойства notes .
@ApiResponses используется для переопределения сообщений по умолчанию, которые сопровождают коды ответов . Для каждого ответного сообщения, которое мы хотим изменить, нам нужно добавить объект @ApiResponse . ****
Например, предположим, что продукт не найден, и наш API возвращает статус HTTP 404 в этом сценарии. Если мы не добавим пользовательское сообщение, исходное сообщение «Не найдено» может быть трудно понять. Вызывающий может интерпретировать это как неправильный URL-адрес. Однако добавление описания «Товар не найден» делает его более понятным.
@ApiParam определяет свойства параметров метода. Его можно использовать вместе с параметрами пути, запроса, заголовка и формы. Мы добавили имя, значение (описание) и пример для параметра «id». Если бы мы не добавили настройку, библиотека подобрала бы только имя и тип параметра, как мы видим на первом изображении.
Посмотрим, как это изменит документацию:
Здесь мы видим название «Получить идентификатор продукта» рядом с путем API /products/{id} . Мы также можем увидеть описание чуть ниже. Кроме того, в разделе «Параметры» у нас есть описание и пример для поля id . И, наконец, в разделе «Ответы» мы можем заметить, как изменились описания ошибок для кодов 200 и 404.
4.2. Добавьте описание и примеры в модель
Мы можем внести аналогичные улучшения в наш метод createProduct() . Кроме того, поскольку метод принимает объект Product , имеет смысл предоставить описание и примеры в самом классе Product .
Давайте внесем некоторые изменения в класс Product , чтобы добиться этого:
@ApiModelProperty(notes = "Product ID", example = "1", required = true)
private Long id;
@ApiModelProperty(notes = "Product name", example = "Product 1", required = false)
private String name;
@ApiModelProperty(notes = "Product price", example = "$100.00", required = true)
private String price;
Аннотация @ApiModelProperty определяет свойства полей. Мы использовали эту аннотацию для каждого поля, чтобы установить его примечания (описание), пример и необходимые свойства.
Давайте перезапустим приложение и еще раз взглянем на документацию нашей модели Product :
Если мы сравним это с исходным изображением документации, мы обнаружим, что новое изображение содержит примеры, описания и красные звездочки (*) для обозначения необходимых параметров.
Добавляя примеры в модели, мы можем автоматически создавать примеры ответов в каждом методе, использующем модель в качестве входных или выходных данных. Например, на изображении, соответствующем методу getProduct() , мы видим, что ответ содержит пример, содержащий те же значения, которые мы указали в нашей модели.
Добавление примеров в нашу документацию важно, потому что это делает форматы значений еще более точными. Если наши модели содержат такие поля, как дата, время или цена, необходим точный формат значения. Предварительное определение формата делает процесс разработки более эффективным как для поставщика API, так и для клиентов API.
5. Вывод
В этой статье мы рассмотрели различные способы улучшить читаемость нашей документации по API. Мы научились документировать методы, параметры, сообщения об ошибках и модели с помощью аннотаций @ApiParam, @ApiOperation, @ApiResponses, @ApiResponse и @ApiModelProperty .
Как всегда, код этих примеров доступен на GitHub .