forked from loafle/openapi-generator-original
6976a8c775
* [Haskell Servant] Upgrade to lts-12 - Upgrade Servant to the latest version - Add Maybe for optional values - Add UUID, UTCTime and Day types - Fix the URL configuration so that it has one param with all data - Add Data and ToSchema instances to models - Switch to TLS http manager so it can connect to https urls - Add nicer API to call the endpoints - Add Nix support * [Haskell Servant] Upgrade Petstore * [Haskell Servant] Delete old swagger-petstore samples * [Haskell Servant] Use generics for ToForm and FromForm instances * [Haskell Servant] Generate ToSchema instance only if it's safe to do
80 lines
2.9 KiB
Markdown
80 lines
2.9 KiB
Markdown
# Auto-Generated OpenAPI Bindings to `OpenAPIPetstore`
|
|
|
|
The library in `lib` provides auto-generated-from-OpenAPI bindings to the OpenAPIPetstore API.
|
|
|
|
## Installation
|
|
|
|
Installation follows the standard approach to installing Stack-based projects.
|
|
|
|
1. Install the [Haskell `stack` tool](http://docs.haskellstack.org/en/stable/README).
|
|
2. Run `stack install` to install this package.
|
|
|
|
Otherwise, if you already have a Stack project, you can include this package under the `packages` key in your `stack.yaml`:
|
|
```yaml
|
|
packages:
|
|
- location:
|
|
git: https://github.com/yourGitOrg/yourGitRepo
|
|
commit: somecommit
|
|
```
|
|
|
|
## Main Interface
|
|
|
|
The main interface to this library is in the `OpenAPIPetstore.API` module, which exports the OpenAPIPetstoreBackend type. The OpenAPIPetstoreBackend
|
|
type can be used to create and define servers and clients for the API.
|
|
|
|
## Creating a Client
|
|
|
|
A client can be created via the `createOpenAPIPetstoreClient` function, which will generate a function for every endpoint of the API.
|
|
Then these functions can be invoked with `runOpenAPIPetstoreClientWithManager` or more conveniently with `callOpenAPIPetstoreClient`
|
|
(depending if you want an `Either` back or you want to catch) to access the API endpoint they refer to, if the API is served
|
|
at the `url` you specified.
|
|
|
|
For example, if `localhost:8080` is serving the OpenAPIPetstore API, you can write:
|
|
|
|
```haskell
|
|
{-# LANGUAGE RecordWildCards #-}
|
|
|
|
import OpenAPIPetstore.API as API
|
|
|
|
import Network.HTTP.Client (newManager)
|
|
import Network.HTTP.Client.TLS (tlsManagerSettings)
|
|
import Servant.Client (ClientEnv, mkClientEnv, parseBaseUrl)
|
|
|
|
|
|
main :: IO ()
|
|
main = do
|
|
-- Configure the BaseUrl for the client
|
|
url <- parseBaseUrl "http://localhost:8080/"
|
|
|
|
-- You probably want to reuse the Manager across calls, for performance reasons
|
|
manager <- newManager tlsManagerSettings
|
|
|
|
-- Create the client (all endpoint functions will be available)
|
|
OpenAPIPetstoreBackend{..} <- API.createOpenAPIPetstoreClient
|
|
|
|
-- Any OpenAPIPetstore API call can go here, e.g. here we call `getSomeEndpoint`
|
|
API.callOpenAPIPetstore (mkClientEnv manager url) getSomeEndpoint
|
|
```
|
|
|
|
## Creating a Server
|
|
|
|
In order to create a server, you must use the `runOpenAPIPetstoreServer` function. However, you unlike the client, in which case you *got* a `OpenAPIPetstoreBackend`
|
|
from the library, you must instead *provide* a `OpenAPIPetstoreBackend`. For example, if you have defined handler functions for all the
|
|
functions in `OpenAPIPetstore.Handlers`, you can write:
|
|
|
|
```haskell
|
|
{-# LANGUAGE RecordWildCards #-}
|
|
|
|
import OpenAPIPetstore.API
|
|
|
|
-- A module you wrote yourself, containing all handlers needed for the OpenAPIPetstoreBackend type.
|
|
import OpenAPIPetstore.Handlers
|
|
|
|
-- Run a OpenAPIPetstore server on localhost:8080
|
|
main :: IO ()
|
|
main = do
|
|
let server = OpenAPIPetstoreBackend{..}
|
|
config = Config "http://localhost:8080/"
|
|
runOpenAPIPetstoreServer config server
|
|
```
|