向 Servant OpenAPI 规范添加描述

如何解决向 Servant OpenAPI 规范添加描述

想要将 OpenAPI 架构、路径、参数的描述添加到所有允许描述子元素的 OpenAPI 元素中。

module Spec.User where

import           Control.Lens
import           Data.Aeson
import           Data.OpenApi
import           Data.Typeable (Typeable)
import           GHC.Generics
import           Servant

data User =
    User
        { name :: String,age :: Int
        }
    deriving (Show,Generic,Typeable)

instance ToJSON User

instance ToSchema User where
    declareNamedSchema proxy = do
        userSchema <- genericDeclareNamedSchema defaultSchemaOptions proxy
        return $ userSchema
            & schema . description ?~ descSchema
            & schema . properties . ix "name" . mapped . description ?~ descName
            & schema . properties . ix "age" . mapped . description ?~ descAge
      where
        descSchema = "This is the description of 'User' schema"
        descName = "This is the description of 'User.name'"
        descAge = "This is the description of 'User.age'"


newtype UserId =
    UserId Integer
    deriving (Show,Typeable,ToJSON)

instance ToSchema UserId

instance ToParamSchema UserId

type GetUsers = Get '[JSON] [User]
type GetUser  = Capture "user_id" UserId :> Get '[JSON] User
type PostUser = ReqBody '[JSON] User :> Post '[JSON] UserId

-- FIXME Add description per path,parameter,and response

type UserAPI  = GetUsers :<|> GetUser :<|> PostUser

模式的文档是可以的，但错误修剪。例如，拼错“姓名”或“年龄”不会导致警告或错误。

但是，目前我更关心的是如何“轻松”和“安全地”将描述添加到路径规范中？ E.G.

paths:
  /users:
    get:
      DESCRIPTION: |
        bla blub ...
      operationId: findUsers
      parameters:
        - name: tags
          in: query
          DESCRIPTION: foo bar ...
          required: false
          style: form
          schema:
            type: array
            items:
              type: string
        - name: limit
          in: query
          DESCRIPTION: baz boo ...
          required: false
          schema:
            type: integer
            format: int32
      responses: ...

解决方法

您需要 servant-openapi3 从 Servant 自动生成 OpenAPI。然后，您可以使用场镜添加额外的注释，例如描述，请参阅 here。