holmusk / servant-docs-simple Goto Github PK

Current the document function is implemented in 2 places.

1. In Servant.Docs.Simple.Parse as a typeclass function for HasDocumentApi
2. In Servant.Docs.Simple to convert a type to PlainText

We should remove this ambiguity and rename 1).

Currently older versions (< 1.6) of Servant have differing implementation for Streams. Hence to support these we should create a new branch which are able to parse these.

A consequence of this is that we can only support resolver >= 8.6.5 and after as older resolvers use (< 1.6) versions of Servant.

Currently only the linux environment for the project can build on Travis CI.

Windows
Currently the install shell script used in .travis.yml isn't friendly to Windows.

OSX
Locally it works (I use OSX while working on this project).
The current GHC 8.6.5 we use errors out with the OSX build environment with Travis CI.
See related issues:
actions/setup-haskell#1
https://travis-ci.community/t/native-support-for-osx-builds/2441

Current output as of v0.2.0.1

After calling typeRep on the format type '[JSON]

Response:
    Format: ': * JSON ('[] *)
    ContentType: User

Preferred output

Response:
    Format: [JSON]
    ContentType: User

Some modifiers are ignored when parsing an API type.

For example, for the following Api Fragment.

ReqBody' m ct typ

Only information from ct and typ are included.

Currently only Response type supports the modifiers.
We should include these in the HasDocument instances for relevant types.

Names for typeclasses in Servant.Docs.Simple.Parse are not sufficiently informative about their usecase.

Solution

• rename HasParsable to HasParsableApi
• rename HasDocumentApi to HasParsableEndpoint

We have added a new API endpoint with a PUT verb to the spec. Unfortunately, on attempting to generate the documentation, no documentation is generated for the PUT endpoint.

Currently the intermediate representation uses a linked list of pairs.

The structure of an API is more similar to a hashmap and this helps to prevent duplicate key:value pairs as well.

Eventually this should be in place.

See if we can optimize for this.

Intermediate structure name is Endpoints.

This introduces ambiguity with the type-family Endpoints from Servant.API.TypeLevel.

Rename to ApiDocs or something else less ambiguous.

I am attempting generate documentation for once of my projects with the following API endpoint:

data MeadowMoodAndJournalingSite route = MeadowMoodAndJournalingSite
  { ... // other endpoints in the same hierarchy
   , mmajsGetEntries :: route
        :- "get-entries"
        :> QueryParam "page-no" Int
        :> QueryParam "search-string" Text
        :> Get '[Proto] Proto.MoodAndJournalEntries
  } deriving stock (Generic)

However, the documentation generated is as follows:

/api/meadow/mood-journaling/get-entries:
Authentication: MEADOW_SESSION
QueryParam:
    Param: search-string
    ContentType: Text
RequestType: 'GET
Response:
    Format: ': * Proto ('[] *)
    ContentType: MoodAndJournalEntries

For some reason, the second query parameter is missed when generating the documentation.

We should include markdown format as it is a commonly used format as well.

We should attempt to output it from the prettyprinter rendered format.

Some refactoring may have to be done with the Renderable instance for prettyprinter, such annotating keywords.

When scrolling through Readme, tutorial segment appears at the bottom. We should add a link to it so Users can easily access the section on tutorials

When examples fail to compile, this throws an error but does not cause the CI build to fail.