Документ Enum в Swagger

1. Обзор

В этом руководстве мы узнаем, как документировать перечисление в Swagger с помощью плагина swagger-maven и проверять сгенерированный документ JSON в редакторе swagger.

2. Что такое чванство?

Swagger — это инструмент с открытым исходным кодом для определения API-интерфейсов на основе отдыха. В современном мире большинство организаций переходят на микросервисы и первый подход к API. Swagger очень удобен для разработки и документирования API. Он также предоставляет различные инструменты, такие как редактор Swagger, пользовательский интерфейс Swagger и Swagger CodeGen, для помощи в разработке API.

Кроме того, Swagger — это реализация спецификаций OpenAPI или OAS , которая определяет набор стандартов для разработки остальных API; следовательно, это помогает организациям по всему миру стандартизировать процесс написания API.

Файл JSON, сгенерированный нашим приложением, также будет соответствовать спецификациям OpenAPI .

Давайте попробуем понять важность Enum в Swagger. Некоторые API требуют, чтобы пользователь придерживался определенного набора предопределенных значений. Эти предопределенные постоянные значения называются enum. Точно так же, когда Swagger предоставляет API-интерфейсы, мы хотим убедиться, что пользователь выбирает значение из этого предопределенного набора, а не свободный текст. Другими словами, нам нужно задокументировать перечисления в нашем файле swagger.json , чтобы пользователь знал о возможных значениях.

3. Реализация

Давайте возьмем пример REST API и перейдем к реализации. Мы реализуем POST API для найма сотрудников в организации на определенные роли. Однако роль может быть только одной из следующих: Engineer , Clerk , Driver или Janitor .

Мы создадим перечисление с именем Role со всеми возможными значениями роли сотрудника и создадим класс Employee , одним из свойств которого является роль. Давайте посмотрим на диаграмму UML, чтобы лучше понять классы и их взаимосвязь:

Чтобы задокументировать это в Swagger, во-первых, мы импортируем и настроим swagger-maven-plugin в нашем приложении. Во-вторых, мы добавим в наш код необходимые аннотации и, наконец, создадим проект и проверим сгенерированный документ swagger или swagger.json в редакторе swagger.

3.1. Импорт и настройка плагина

Мы собираемся использовать swagger-maven-plugin , ** ** и нам нужно добавить его как зависимость к pom.xml нашего приложения:

<dependency>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
</dependency>

Кроме того, чтобы настроить и включить этот плагин, мы добавим его в раздел плагинов файла pom.xml :

• location : этот тег указывает пакеты или классы, содержащие @Api , разделенные точкой с запятой.
• информация : этот тег предоставляет метаданные для API. Swagger-ui использует эти данные для отображения информации
• swaggerDirectory : этот тег определяет путь к файлу swagger.json.

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>com.foreach.swaggerenums.controller</locations>
                <schemes>http,https</schemes>
                <host>foreach.com</host>
                <basePath>/api</basePath>
                <info>
                    <title>ForEach - Document Enum</title>
                    <version>v1</version>
                    <description>This is a ForEach Document Enum Sample Code</description>
                    <contact>
                        <email>pmurria@foreach.com</email>
                        <name>Test</name>
                    </contact>
                    <license>
                        <url>https://www.apache.org/licenses/LICENSE-2.0.html</url>
                        <name>Apache 2.0</name>
                    </license>
                </info>
                <swaggerDirectory>generated/swagger-ui</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
     </executions>
 </plugin>

3.2. Документирование перечисления

Чтобы задокументировать перечисление в Swagger, нам нужно объявить модели с помощью аннотации @ApiModel.

В этом примере мы создали enum Role с четырьмя возможными значениями — Engineer, Clerk, Driver и Janitor . Поскольку нам нужно задокументировать это перечисление, мы добавим @ApiModel в роль перечисления . Другими словами, это позволит Swagger узнать о наличии модели. В классе Employee мы аннотируем Employee с помощью @ApiModel и Role с помощью @ApiModelProperty .

Наши Сотрудник, Роль и HireController будут выглядеть так:

@ApiModel
public class Employee {
    @ApiModelProperty
    public Role role;

   // standard setters and getters
}

@ApiModel
public enum Role {
    Engineer, Clerk, Driver, Janitor;
}

Далее мы создадим API с @Path как «/hire» и будем использовать модель Employee в качестве входного параметра для метода наймаEmployee . Мы должны добавить @Api в наш HireController , чтобы swagger -maven-plugin был в курсе и должен учитывать это для документирования:

@Api
@Path(value="/hire")
@Produces({"application/json"})
public class HireController {

    @POST
    @ApiOperation(value = "This method is used to hire employee with a specific role")
    public String hireEmployee(@ApiParam(value = "role", required = true) Employee employee) {
        return String.format("Hired for role: %s", employee.role.name());
    }
}

3.3. Создание документа Swagger

Чтобы собрать наш проект и сгенерировать документ swagger, выполните следующую команду:

mvn clean install

После создания подключаемый модуль сгенерирует файл swagger.json в папке generate/swagger-ui или в месте, указанном в подключаемом модуле. Глядя на определения, мы увидим роль перечисления, задокументированную внутри свойств сотрудника, со всеми ее возможными значениями.

"definitions" : {
  "Employee" : {
    "type" : "object",
    "properties" : {
      "role" : {
        "type" : "string",
        "enum" : [ "Engineer", "Clerk", "Driver", "Janitor" ]
      }
    }
  }
}

Теперь мы визуализируем сгенерированный JSON с помощью онлайн-редактора swagger и ищем роль перечисления :

4. Вывод

В этом руководстве мы обсудили, что такое Swagger, и узнали о спецификации OpenAPI и ее важности в разработке API для организаций. Кроме того, мы создали и задокументировали наш образец API, содержащий enum, с помощью swagger-maven-plugin . Наконец, для проверки вывода мы использовали редактор swagger для визуализации сгенерированного документа JSON.

Эту реализацию можно найти на GitHub.