Как я могу добавить внешнюю документацию API В Swagger с использованием виноградарства?

Question

Как я могу добавить внешнюю документацию API?

Например, я пользуюсь привратником, POST /api/v1/token Это не конечная точка винограда. Как добавить эту конечную точку в swagger?

Answer 1

У меня сегодня та же проблема. Я использую Grape для своего API и использую Doorkeeper в качестве поставщика OAuth 2. Doorkeeper предоставляет несколько конечных точек API, таких как POST /oauth/authorize, POST /oauth/token.

Я добавляю манекен oauth api class к своим API, описывая каждую конечную точку, используя desc и params. Конечно, мне приходится вручную перечислять все параметры (требуется или необязательно, имя, тип, desc, значения и т. Д.). Но я оставляю реализацию пустой. Когда пользователь вызывает эти apis, запросы будут перенаправлены в Doorkeeper для выполнения реального действия.

Например, мой код о POST /oauth/token конечной точки:

module API 
    class Oauth < Grape::API 
    resources :oauth do 
     # POST /oauth/token 
     desc 'Requires for an access token' 
     params do 
     requires :grant_type, 
       type: String, 
       values: %w(client_credentials authorization_code) 
     optional :code, 
       type: String 
     requires :client_id, 
       type: String 
     requires :client_secret, 
       type: String 
     optional :redirect_uri, 
       type: String, 
       default: 'urn:ietf:wg:oauth:2.0:oob' 
     end 
     post :token do 
     end 
    end # resources :oauth 

    add_swagger_documentation mount_path: 'oauth/swagger_doc', 
           api_version: '', 
           format: :json, 
           hide_format: true, 
           hide_documentation_path: true 
    end 
end 

И сгенерированного развязность документ: