README.md · typeable/compaREST

git.iko.soy/typeable/compaREST

330 lines 10.0 kB history raw

1# compaREST

3[![Hackage](https://img.shields.io/hackage/v/compaREST.svg?logo=haskell)](https://hackage.haskell.org/package/compaREST)

4[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

6Compatibility checker for OpenAPI

8## Using compaREST in Github Actions

10Add the following step to your Github Actions workflow:

12```yaml

13- uses: typeable/comparest

14 if: ${{ github.event_name == 'pull_request' }}

15 with:

16 old: old-openapi.yaml

17 new: new-openapi.yaml

18```

20The `new` and `old` values should be paths to your OpenAPI specifications you want to compare.

22You will get something like this in your pull requests:

24![](docs/img/github-action-report.png)

26For more detail please see our [integration guide](docs/Integration_guide.md).

28## An example

30### Your situation

32You are developing a very important server with a REST API. You have clients who use your API that you do not control. Say, you are also developing a mobile app that uses your API and you can't force someone to update to the latest version. (Or you prefer not to for UX reasons.)

34You have recently released version 1.0 and things are going great: user are downloading your app, servers are processing requests.

36You describe your API in a file `api-1.0.0.yaml`:

38```yaml

39openapi: "3.0.0"

40info:

41 version: 1.0.0

42 title: Swagger Petstore

43 license:

44 name: MIT

45servers:

46 - url: https://example.com

47paths:

48 /pets:

49 get:

50 parameters:

51 - name: limit

52 in: query

53 required: false

54 schema:

55 type: integer

56 maximum: 20

57 responses:

58 "200":

59 description: ""

60 headers:

61 x-next:

62 schema:

63 type: string

64 content:

65 application/json:

66 schema:

67 $ref: "#/components/schemas/Pets"

68 post:

69 requestBody:

70 content:

71 application/json:

72 schema:

73 $ref: "#/components/schemas/Pet"

74 responses:

75 "201":

76 description: ""

77components:

78 schemas:

79 Pet:

80 type: object

81 required:

82 - id

83 - name

84 properties:

85 id:

86 type: integer

87 name:

88 type: string

89 minLength: 3

90 maxLength: 10

91 Pets:

92 type: array

93 items:

94 $ref: "#/components/schemas/Pet"

95```

97### Evolving your product

99Enthused over your initial success you hurry to release a new and improved version of your API and mobile app.

100

101After a round of very intense programming you take a look at your new `api-1.1.0.yaml`:

102

103```yaml

104openapi: "3.0.0"

105info:

106 version: 1.1.0

107 title: Swagger Petstore

108 license:

109 name: MIT

110servers:

111 - url: https://example.com

112paths:

113 /pets:

114 get:

115 parameters:

116 - name: limit

117 in: query

118 required: false

119 schema:

120 type: integer

121 maximum: 30

122 responses:

123 "200":

124 description: ""

125 headers:

126 x-next:

127 schema:

128 type: string

129 content:

130 application/json:

131 schema:

132 $ref: "#/components/schemas/Pets"

133 post:

134 requestBody:

135 content:

136 application/json:

137 schema:

138 $ref: "#/components/schemas/Pet"

139 responses:

140 "201":

141 description: ""

142components:

143 schemas:

144 Pet:

145 type: object

146 required:

147 - id

148 - name

149 properties:

150 id:

151 type: integer

152 name:

153 type: string

154 minLength: 1

155 maxLength: 15

156 weight:

157 type: integer

158 Pets:

159 type: array

160 items:

161 $ref: "#/components/schemas/Pet"

162```

163

164Looking at the very large and complex API description, you grow more and more concerned that your old mobile app might stop working when you update the server. But the spec is too large and too complex to reasonably assess this manually.

165

166### Assessing compatibility automatically

167

168Luckily, you have access to compaREST which can programmatically analyze your APIs and determine what, if anything, breaks compatibility and what doesn't.

169

170You can call it, passing the API your client will be aware of, and the API your server will serve like so:

171

172```bash

173docker run --rm -v $(pwd):/data:rw typeable/comparest --client /data/api-1.0.0.yaml --server /data/api-1.1.0.yaml --output /data/report.md

174```

175

176Running this command will output a file `report.md`, containing the compatibility report between the two APIs:

177

178> # Summary

179>

180> | [❌ Breaking changes](#breaking-changes) | [⚠️ Non-breaking changes](#non-breaking-changes) |