向仆人 OpenAPI 规范添加描述

Question

想要将描述添加到 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, Generic, 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

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

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

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: ...

Answer 1

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