Swagger

[info] Jeśli pracujesz na laboratorium, aby rozpocząć realizację kolejnego modułu, musisz wykonać poniższe operacje

• sklonuj repozytorium ze swoim kodem (git clone ŚCIEŻKA_DO_REPOZYTORIUM),

• zainstaluj potrzebne gemy (bundle install --path vendor/bundle),

• dokonaj migracji bazy danych (rails db:migrate)

• uruchom serwer (rails server)

Ostatnim krokiem przed przystąpieniem do pracy nad aplikacją mobilną, będzie przygotowanie dokumentacji naszego interfejsu programistycznego. Przygotujemy ją za pomocą narzędzia Swagger.

Dokumentacja będzie generowana na niewielkich wstawek kodu, które dodamy przed dokumentowanymi metodami. Na początek uzupełnimy nasz gemset o generator dokumentacji. Dodajmy do pliku Gemfile następującą linię.

gem 'swagger-docs'

Następnie aktualizujemy gemset.

• bundle update --path vendor/bundle

Niektóre gemy potrzebują dodatkowej konfiguracji. Zachodzi ona przy użyciu tak zwanych inicjalizatorów, znajdujących się w katalogu config/initializers. Utwórzmy w takim razie inicjalizator Swaggera config/initializers/swagger.rb.

Określamy w nim katalog, w którym chcemy wygenerować nasz plik z dokumentacją (public/), ścieżkę pod którą działa serwer (http://localhost:3000) oraz skrócony opis w formie nazwy (title) i opisu (description) projektu.

# config/initializers/swagger-docs.rb
Swagger::Docs::Config.register_apis({
  "1.0" => {
    :api_file_path => "public/",
    :base_path => "http://localhost:3000",
    :clean_directory => true,
    :parent_controller => ApplicationController,
    :attributes => {
      :info => {
        "title" => "Student forum",
        "description" => "Example rails app"
      }
    }
  }
})

W każdym z kontrolerów, które zamierzamy dokumentować musimy dodać informację o tym, jak przedstawiać nazwę zasobu. Dokumentację rozpoczniemy od kontrolera studenta, więc uzupełnijmy go o odpowiednią dyrektywę.

class StudentsController < ApplicationController
  ...
  swagger_controller :students, 'Students'
  ...
end

Jako pierwszą, zajmiemy się stosunkowo prostą metodą index. Tuż przed jej implementacją dodajemy blok swagger_api w argumencie przyjmujący jej nazwę (:index). Wewnątrz, w obligatoryjnym parametrze summary przekazujemy jej zastosowanie (Zwraca listę wszystkich studentów, a więc Returns all students). Możemy też uzupełnić ją o dłuższy opis zasady działania (parametr notes).

class StudentsController < ApplicationController
  ...
  # GET /students
  # GET /students.json
  swagger_api :index do
    summary 'Returns all students'
    notes 'Notes...'
  end
  def index
    @students = Student.all
  end
  ...
end

Przed każdą regeneracją dokumentacji powinniśmy zatrzymać serwer. Aby ją wygenerować, używamy zadania swagger:docs.

• rails swagger:docs

Dokumentacja jest przechowywana jako opis w postaci kilku plików json, które właśnie zapisały się w katalogu public projektu. Poza dokumentacją samą w sobie potrzebujemy jeszcze interfejsu, który będzie w stanie ją zinterpretować i wyświetlić. Pobierzemy go i zapiszemy w tym samym folderze.

W terminalu, przejdźmy do katalogu public.

• cd public

Dodajmy submoduł gita zawierający interfejs Swaggera.

• git submodule add [e-mail]:swagger-api/swagger-ui.git swagger

Niestety, gem swagger-docs nie jest już aktualizowany od dłuższego czasu, więc musimy cofnąć wersję interfejsu Swaggera do ostatniej wspierającej wygenerowane przez nas dane. Przejdźmy więc do katalogu pobranego interfejsu.

• cd swagger

I przestawmy go na wersję 2.2.8.

• git checkout v2.2.8

Dokumentacja interfejsu powinna być dostępna obok aplikacji, tak samo jak każdy z jej widoków. Umieścimy ją w ścieżce /api. W tym celu musimy zaktualizować nasze routes.rb.

get '/api' => redirect('/swagger/dist/index.html?url=/api-docs.json')

Po ponownym uruchomieniu serwera, możemy już odwiedzić dokumentację pod łączem http://localhost:3000/api

Każda sekcja dokumentacji opisuje osobny kontroler. W każdym z nich możemy rozwinąć udokumentowane akcje. Również każdą akcję możemy rozwinąć i przetestować przyciskiem Try it out.

Przekazywanie parametrów

Nie każda metoda jest tak prosta jak listowanie wszystkich studentów. Zajmijmy się dokumentacją metody show kontrolera studenta. Przyjmuje ona parametr id z identyfikatorem studenta, którego widok chcemy pobrać. Użytkownik przekazuje go w ścieżce do zasobu (przykładowo /students/1 odnosi nas do strony studenta o id = 1).

Dokumentacja takiej metody musi zostać zatem uzupełniona o parametr (param) z argumentem ścieżki (:path), nazwą (:id). Jako typ określamy go jako liczbę całkowitą :integer. Każdy argument ścieżki musimy określić jako wymagany (:required). Na koniec dodajemy do niej wyjaśnienie (summary).

  # GET /students/1
  # GET /students/1.json
  swagger_api :show do
    summary 'Returns one student'
    param :path, :id, :integer, :required, "Students id"
    notes 'Notes...'
  end
  def show
  end

Możemy zaktualizować dokumentację. Pamiętajmy aby najpierw wyłączyć serwer.

• rake swagger:docs

W liście metod API studenta pojawił się dodatkowy wpis. Tym razem, aby przetestować metodę, musimy wprowadzić również wartość parametru.

Poza parametrami ścieżki (:path) możemy także przekazywać parametry, które oryginalnie znajdowałyby się w formularzu. Na początek jednak, podobnie jak w poprzednim module dla sesji, wyłączmy w kontrolerze studenta zabezpieczenie autentykacji formularzy.

class StudentsController < ApplicationController
  skip_before_action :verify_authenticity_token
  ...
end

Dobrym przykładem metody korzystającej z pól formularza może być tworzenie nowego studenta. Parametry formularza są typu :form. Jako ich nazwę przyjmujemy nazwę zasobu z nazwą parametru w nawiasie kwadratowym (student[name]).

  swagger_api :create do
   summary "Create a student"
   param :form, "student[name]", :string, :required, "Students name"
   param :form, "student[index]", :string, :required, "Students index"
   param :form, "student[password]", :string, :required, "Students password"
  end

Po zregenerowaniu dokumentacji (i ponownym uruchomieniu serwera) możemy z jej poziomu utworzyć nowego studenta.

Mamy także gotową obsługę błędów walidacji.

Uzyskiwanie tokena

Niektóre metody muszą być zabezpieczone tokenem. Zanim się nimi zajmiemy, musimy udokumentować samo uzyskanie tokena od kontrolera sesji. Aby zdobyć token, do metody create przesyłamy formularz z danymi do logowania (index i password).

class SessionsController < ApplicationController
  skip_before_action :verify_authenticity_token
  swagger_controller :session, "Authentication"

  ...

  swagger_api :create do
    summary "Gather a token"
    param :form, "session[index]", :string, :required, "Students index"
    param :form, "session[password]", :string, :required, "Students password"
  end
  def create
    ...
  end

  ...

end

Metody autentykowane

Aby, przykładowo, założyć nowy temat, musimy najpierw zautentykować się jako student. Na początek zadeklarujmy w kontrolerze tematu sam fakt dokumentacji (swagger_controller. Przy okazji wyłączamy autentykowanie formularzy. Deklarujemy również wymaganie autentykacji, żądając uruchomienia metody require_token przed wywołaniem metody create.

class TopicsController < ApplicationController
  skip_before_action :verify_authenticity_token
  ...
  before_action :require_token, only: [:create]
  ...
  swagger_controller :topics, 'Topics'
  ...
end

Następnie zaktualizujemy widok tematu (_topic.json.jbuilder) tak, aby po utworzeniu go nie przekazywał jego ścieżki.

  json.extract! topic, :id, :title, :student_id, :course_id, :created_at, :updated_at

Rezygnujemy z przekazywania ścieżki w odpowiedzi również przy poprawnym wyniku zapytania w metodzie create kontrolera tematu.

  # POST /topics
  # POST /topics.json
  def create
    @course = Course.find(params[:course_id])
    @topic = @course.topics.new(topic_params)
    @topic.student = current_student

    respond_to do |format|
      if @topic.save
        format.html { redirect_to [@course, @topic], notice: 'Topic was successfully created.' }
        format.json { render :show, status: :created }
      else
        format.html { render :new }
        format.json { render json: @topic.errors, status: :unprocessable_entity }
      end
    end
  end

Możemy przejść do implementacji naszej dokumentacji. Poza parametrem ścieżki (:path) z identyfikatorem kursu i formularzem zawierającym ciało posta (:form), znajduje się w niej także parametr nagłówka (:header) Z kluczem Authorization.

  swagger_api :create do
   summary "Create new topic"
   param :header, "Authorization", :string, :required, "Authentication token"
   param :path, :course_id, :integer, :required, "Course id"
   param :form, "topic[title]", :string, :required, "Title of a topic"
  end

Po wygenerowaniu dokumentacji i ponownym uruchomieniu serwera, możemy przetestować działanie przykładu. Pamiętajmy, że token przekazujemy nie jedynie jako sam uzyskany klucz, ale przez parę Token KLUCZ.

Bardzo ważna jest wielka litera na początku słowa Token i spacja pomiędzy nim a kluczem.

Wiemy już wszystko, co konieczne, aby wygenerować pełną dokumentację projektu.

[info] Aktualny kod

Na koniec każdego modułu znajduje się łącze do pełnej wersji kodu, który powinien być jego wynikiem.

• Wprowadzone zmiany

• Pełen kod