Статьи

Swagger легко документировать ваш REST API Play Framework

Январь 24, 2019

Я использовал Play Framework в качестве молниеносного REST-фреймворка на основе Java для нескольких проектов. Позже я был рад найти Swagger и работал над тем, чтобы интегрировать его в несколько проектов. Когда я боролся с этим в первый раз, я подумал, что было бы полезно поделиться своим опытом и создать статью с практическими рекомендациями, описывающую шаги для быстрого достижения успеха.

Чтобы упростить ситуацию, я начал с существующего проекта Play Framework, Java, JPA, REST, созданного Джеймсом Уордом . Проект Джеймса находится на GitHub, поэтому вам стоит потянуть его, прежде чем начать с этим практическим руководством.

Инструкции

  1. Сначала добавьте зависимости в ваш build.sbt. Мне удалось решить проблему с зависимостями с версией Play Framework 2.3.0, используемой в примере проекта и Swagger-Core, обратившись к выпуску GitHub 55o: https: // github .com / s w a г г е р — р я / с ш а е г е р — с Н / I S S е е / 550 .
    1
    2
    3
    "com.wordnik" %% "swagger-play2" % "1.3.12" exclude("org.reflections", "reflections"),
    "org.reflections" % "reflections" % "0.9.8" notTransitive (),
    "org.webjars" % "swagger-ui" % "2.1.8-M1"
  2. Добавьте это в конфигурационное приложение.conf:

    api.version="1.0" swagger.api.basepath="http://localhost:9000"

  3. Добавьте маршруты api-docs в файл маршрутов:
    01
    02
    03
    04
    05
    06
    07
    08
    09
    10
    11
    12
    GET / controllers.Assets.at(path="/public", file="index.html")
     
    GET /api-docs controllers.ApiHelpController.getResources
     
    POST /login controllers.SecurityController.login() POST /logout controllers.SecurityController.logout()
     
    GET /api-docs/api/todos controllers.ApiHelpController.getResource(path = "/api/todos")
    GET /todos controllers.TodoController.getAllTodos()
    POST /todos controllers.TodoController.createTodo()
     
    # Map static resources from the /public folder to the /assets URL path
    GET /assets/*file controllers.Assets.at(path="/public", file)
  4. Добавьте аннотации Swagger в ToDoController (@Api):
    1
    2
    3
    @Api(value = "/api/todos", description = "Operations with Todos")
    @Security.Authenticated(Secured.class)
    public class TodoController extends Controller {

    Затем аннотации для методов GET и POST:

    01
    02
    03
    04
    05
    06
    07
    08
    09
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    @ApiOperation(value = "get All Todos",
         notes = "Returns List of all Todos",
         response = Todo.class,
         httpMethod = "GET")
    public static Result getAllTodos() {
         return ok(toJson(models.Todo.findByUser(SecurityController.getUser())));
    }
    @ApiOperation(
         nickname = "createTodo",
         value = "Create Todo",
         notes = "Create Todo record",
         httpMethod = "POST",
         response = Todo.class
     )
    @ApiImplicitParams(
         {
              @ApiImplicitParam(
                   name = "body",
                   dataType = "Todo",
                   required = true,
                   paramType = "body",
                   value = "Todo"
              )
         }
    )
    @ApiResponses(
              value = {
                      @com.wordnik.swagger.annotations.ApiResponse(code = 400, message = "Json Processing Exception")
              }
    )
    public static Result createTodo() {
         Form<models.Todo> form = Form.form(models.Todo.class).bindFromRequest();
         if (form.hasErrors()) {
             return badRequest(form.errorsAsJson());
         }
         else {
              models.Todo todo = form.get();
              todo.user = SecurityController.getUser();
              todo.save();
              return ok(toJson(todo));
         }
    }
  5. Запустите приложение и перейдите по этому URL в вашем браузере:

    http://localhost:9000/assets/lib/swagger-ui/index.html?/url=http://localhost:9000/api-docs

Исходный код

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

ПРИМЕЧАНИЕ: тем временем, Джеймс Уорд одобрил мой запрос на добавление, чтобы добавить эти изменения в свой проект — GitHub, так что вы должны получить его

Ссылка: Легко документировать свой REST API Play Framework с помощью Swagger от нашего партнера по JCG Брайана Портера в блоге Poornerd .
40
Share: