GetShopTV/swagger2

Architecture-independent encoding for Swagger

Open

#98 opened on Apr 19, 2017

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Haskell (61 forks)github user discovery
help wanted

Repository metrics

Stars
 (74 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

Currently I'm using encodePretty to generate swagger.json. However, encodePretty is not exactly a "drop-in replacement for aeson's encode" since it relies on toJSON while encode uses toEncoding.

This results in different key ordering on 32-bit and 64-bit machines and unnecessary diffs for swagger.json when locally someone has a different number of bits.

IIUC we provide toEncoding method implementations for some types to enforce key ordering for InsOrdHashMaps. However, we don't do that for many record types, such as Info and therefore we get different field ordering in encoding for those types.

Also, if I get it right, DEFINE_ENCODING provides an SoP-derived encoding that is architecture-independent.

@phadej would it be sufficient to add DEFINE_TOENCODING for all record types that constitute Swagger to get an architecture-independent toEncoding for Swagger?

It would be extra nice to also have an encodePretty that would use toEncoding rather than toJSON and preserve the ordering of keys.

Contributor guide

Research direction
Investigate which record types in the Swagger data model are missing toEncoding definitions and add DEFINE TOENCODING for each. Optionally, create a new encodePretty function that uses toEncoding instead of toJSON to ensure consistent key ordering across architectures.
Tech stack
haskell
Domain
backend
Issue type
Bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
HaskellaesonTemplate Haskell
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65