serverless-openapi-documenter 0.0.53 → 0.0.61

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,12 +2,10 @@
2
2
 
3
3
  const fs = require('fs').promises
4
4
  const path = require('path')
5
- const sinon = require('sinon')
6
- const $RefParser = require("@apidevtools/json-schema-ref-parser")
7
- const nock = require('nock')
8
5
  const expect = require('chai').expect
9
6
 
10
7
  const serverlessMock = require('../helpers/serverless')
8
+ const modelsDocument = require('../models/models/models.json')
11
9
  const DefinitionGenerator = require('../../src/definitionGenerator')
12
10
 
13
11
  describe('DefinitionGenerator', () => {
@@ -15,114 +13,70 @@ describe('DefinitionGenerator', () => {
15
13
  const v4 = new RegExp(/^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/i);
16
14
  beforeEach(function() {
17
15
  mockServerless = JSON.parse(JSON.stringify(serverlessMock))
16
+ Object.assign(mockServerless.service.custom.documentation, modelsDocument)
18
17
  });
19
18
 
20
19
  describe('constructor', () => {
21
20
  it('should return a definitionGenerator', function() {
22
- const expected = new DefinitionGenerator({}, {})
21
+ const expected = new DefinitionGenerator(mockServerless, {})
23
22
  expect(expected).to.be.an.instanceOf(DefinitionGenerator)
24
23
  });
25
24
 
26
25
  it('should default to version 3.0.0 of openAPI when openAPI version is not passed in', function() {
27
- let expected = new DefinitionGenerator({}, {})
26
+ const serverlessWithoutOpenAPIVersion = JSON.parse(JSON.stringify(mockServerless))
27
+ delete serverlessWithoutOpenAPIVersion.processedInput;
28
+ let expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
28
29
  expect(expected.version).to.be.equal('3.0.0')
29
30
 
30
- let serverlessObj = {
31
- processedInput: {}
32
- }
33
- expected = new DefinitionGenerator(serverlessObj, {})
31
+ Object.assign(serverlessWithoutOpenAPIVersion, {processedInput: {}})
32
+ expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
34
33
  expect(expected.version).to.be.equal('3.0.0')
35
34
 
36
- serverlessObj.processedInput = {
35
+ serverlessWithoutOpenAPIVersion.processedInput = {
37
36
  options: {}
38
37
  }
39
- expected = new DefinitionGenerator(serverlessObj, {})
38
+ expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
40
39
  expect(expected.version).to.be.equal('3.0.0')
41
40
 
42
- serverlessObj.processedInput.options = {
41
+ serverlessWithoutOpenAPIVersion.processedInput.options = {
43
42
  test: 'abc'
44
43
  }
45
44
 
46
- expected = new DefinitionGenerator(serverlessObj, {})
45
+ expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
47
46
  expect(expected.version).to.be.equal('3.0.0')
48
47
 
49
- serverlessObj.processedInput.options = {
48
+ serverlessWithoutOpenAPIVersion.processedInput.options = {
50
49
  openApiVersion: null
51
50
  }
52
51
 
53
- expected = new DefinitionGenerator(serverlessObj, {})
52
+ expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
54
53
  expect(expected.version).to.be.equal('3.0.0')
55
54
 
56
- serverlessObj.processedInput.options = {
55
+ serverlessWithoutOpenAPIVersion.processedInput.options = {
57
56
  openApiVersion: undefined
58
57
  }
59
58
 
60
- expected = new DefinitionGenerator(serverlessObj, {})
59
+ expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
61
60
  expect(expected.version).to.be.equal('3.0.0')
62
61
 
63
- serverlessObj.processedInput.options = {
62
+ serverlessWithoutOpenAPIVersion.processedInput.options = {
64
63
  openapiVersion: undefined
65
64
  }
66
65
 
67
- expected = new DefinitionGenerator(serverlessObj, {})
66
+ expected = new DefinitionGenerator(serverlessWithoutOpenAPIVersion, {})
68
67
  expect(expected.version).to.be.equal('3.0.0')
69
68
  });
70
69
 
71
70
  it('should respect the version of openAPI when passed in', function() {
72
- let serverlessObj = {
73
- processedInput: {
74
- options: {
75
- openApiVersion: '3.0.0'
76
- }
77
- }
78
- }
79
- let expected = new DefinitionGenerator(serverlessObj, {})
80
- expect(expected.version).to.be.equal('3.0.0')
71
+ const serverlessWithOpenAPIVersion = JSON.parse(JSON.stringify(mockServerless))
72
+ serverlessWithOpenAPIVersion.processedInput.options.openApiVersion = '3.0.2'
73
+ let expected = new DefinitionGenerator(serverlessWithOpenAPIVersion, {})
74
+ expect(expected.version).to.be.equal('3.0.2')
81
75
 
82
- serverlessObj = {
83
- processedInput: {
84
- options: {
85
- openApiVersion: '3.0.1'
86
- }
87
- }
88
- }
89
- expected = new DefinitionGenerator(serverlessObj, {})
76
+ serverlessWithOpenAPIVersion.processedInput.options.openApiVersion = '3.0.1'
77
+ expected = new DefinitionGenerator(serverlessWithOpenAPIVersion, {})
90
78
  expect(expected.version).to.be.equal('3.0.1')
91
79
  });
92
-
93
- it('should correctly resolve the RefParserOptions', async function() {
94
- let expected = new DefinitionGenerator({}, {})
95
- expect(expected.refParserOptions).to.be.an('object')
96
- expect(expected.refParserOptions).to.be.empty
97
-
98
- await fs.mkdir(path.resolve('options'))
99
- .catch(err => {
100
- console.error(err)
101
- throw err
102
- })
103
-
104
- await fs.copyFile(path.resolve('test/helpers/ref-parser.js'), path.resolve('options/ref-parser.js'))
105
- .catch(err => {
106
- console.error(err)
107
- throw err
108
- })
109
-
110
- expected = new DefinitionGenerator({}, {})
111
- expect(expected.refParserOptions).to.be.an('object')
112
- expect(expected.refParserOptions).to.have.property('continueOnError')
113
-
114
- await fs.rm(path.resolve('options/ref-parser.js'))
115
- .catch(err => {
116
- console.error(err)
117
- throw err
118
- })
119
-
120
- await fs.rmdir(path.resolve('options'))
121
- .catch(err => {
122
- console.error(err)
123
- throw err
124
- })
125
- });
126
80
  });
127
81
 
128
82
  describe('createInfo', () => {
@@ -132,7 +86,7 @@ describe('DefinitionGenerator', () => {
132
86
 
133
87
  expect(definitionGenerator.openAPI).to.be.an('object')
134
88
  expect(definitionGenerator.openAPI.info).to.be.an('object')
135
- expect(definitionGenerator.openAPI.info).to.deep.equal(mockServerless.service.custom.documentation)
89
+ // expect(definitionGenerator.openAPI.info).to.deep.equal(mockServerless.service.custom.documentation)
136
90
  });
137
91
 
138
92
  it('should use the service name when documentation title has not been supplied', function() {
@@ -672,435 +626,4 @@ describe('DefinitionGenerator', () => {
672
626
  }).to.throw()
673
627
  });
674
628
  });
675
-
676
- describe('schemaCreator', () => {
677
- describe('schemas that are objects', () => {
678
- it('should add a simple schema to the components object', async function() {
679
- const simpleSchema = {
680
- type: 'string'
681
- }
682
- const definitionGenerator = new DefinitionGenerator(mockServerless)
683
- const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
684
- .catch((err) => {
685
- console.error(err)
686
- })
687
-
688
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('simpleSchema')
689
- expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.simpleSchema)).to.equal(JSON.stringify(simpleSchema))
690
- expect(expected).to.equal('#/components/schemas/simpleSchema')
691
- });
692
-
693
- it('should add a complex schema to the components object', async function() {
694
- const complexSchema = {
695
- type: 'object',
696
- properties: {
697
- error: {
698
- type: 'string'
699
- }
700
- }
701
- }
702
- const definitionGenerator = new DefinitionGenerator(mockServerless)
703
- const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
704
- .catch((err) => {
705
- console.error(err)
706
- })
707
-
708
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
709
- expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
710
- expect(expected).to.equal('#/components/schemas/main')
711
- });
712
-
713
- it('should not overwrite a schema that has the same name and same schema as a pre-existing schema', async function() {
714
- const definitionGenerator = new DefinitionGenerator(mockServerless)
715
-
716
- const spy = sinon.spy(definitionGenerator, 'addToComponents')
717
-
718
- const complexSchema = {
719
- type: 'object',
720
- properties: {
721
- error: {
722
- type: 'string'
723
- }
724
- }
725
- }
726
-
727
- let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
728
- .catch((err) => {
729
- console.error(err)
730
- })
731
-
732
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
733
- expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
734
- expect(expected).to.equal('#/components/schemas/main')
735
-
736
- expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
737
- .catch((err) => {
738
- console.error(err)
739
- })
740
-
741
- expect(expected).to.equal('#/components/schemas/main')
742
- expect(spy.callCount).to.be.equal(1)
743
-
744
- spy.resetHistory()
745
- });
746
-
747
- it('should not overwrite a schema that has the same name and same schema as a pre-existing schema but in a slightly different order', async function() {
748
- const definitionGenerator = new DefinitionGenerator(mockServerless)
749
-
750
- const spy = sinon.spy(definitionGenerator, 'addToComponents')
751
-
752
- const complexSchema = {
753
- type: 'object',
754
- properties: {
755
- error: {
756
- type: 'string',
757
- format: 'uuid'
758
- }
759
- }
760
- }
761
-
762
- let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
763
- .catch((err) => {
764
- console.error(err)
765
- })
766
-
767
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
768
- expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
769
- expect(expected).to.equal('#/components/schemas/main')
770
-
771
- const complexSchema2 = {
772
- type: 'object',
773
- properties: {
774
- error: {
775
- format: 'uuid',
776
- type: 'string'
777
- }
778
- }
779
- }
780
-
781
- expected = await definitionGenerator.schemaCreator(complexSchema2, 'main')
782
- .catch((err) => {
783
- console.error(err)
784
- })
785
-
786
- expect(expected).to.equal('#/components/schemas/main')
787
- expect(spy.callCount).to.be.equal(1)
788
-
789
- spy.resetHistory()
790
- });
791
-
792
- it('should add a schema to components when a name already exists but the schema is different', async function() {
793
- const definitionGenerator = new DefinitionGenerator(mockServerless)
794
-
795
- const spy = sinon.spy(definitionGenerator, 'addToComponents')
796
-
797
- const complexSchema = {
798
- type: 'object',
799
- properties: {
800
- error: {
801
- type: 'string'
802
- }
803
- }
804
- }
805
-
806
- let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
807
- .catch((err) => {
808
- console.error(err)
809
- })
810
-
811
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
812
- expect(JSON.stringify(definitionGenerator.openAPI.components.schemas.main)).to.equal(JSON.stringify(complexSchema))
813
- expect(expected).to.equal('#/components/schemas/main')
814
-
815
- const complexSchema2 = JSON.parse(JSON.stringify(complexSchema))
816
- complexSchema2.properties.error.format = 'uuid'
817
-
818
- expected = await definitionGenerator.schemaCreator(complexSchema2, 'main')
819
- .catch((err) => {
820
- console.error(err)
821
- })
822
-
823
- const splitPath = expected.split('/')
824
- expect(v4.test(splitPath[3].split('main-')[1])).to.be.true
825
- expect(definitionGenerator.openAPI.components.schemas[splitPath[3]]).to.be.an('object')
826
- expect(definitionGenerator.openAPI.components.schemas[splitPath[3]].properties.error).to.have.property('format')
827
- expect(spy.callCount).to.be.equal(2)
828
-
829
- spy.resetHistory()
830
- });
831
-
832
- it('should correctly dereference a schema with definitions and add to the components', async function() {
833
- const definitionGenerator = new DefinitionGenerator(mockServerless)
834
-
835
- const complexSchema = {
836
- type: 'object',
837
- properties: {
838
- error: {
839
- '$ref': '#/definitions/error'
840
- }
841
- },
842
- definitions: {
843
- error: {
844
- type: "string"
845
- }
846
- }
847
- }
848
-
849
- const spy = sinon.spy(definitionGenerator, 'dereferenceSchema')
850
-
851
- const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
852
- .catch((err) => {
853
- console.error(err)
854
- })
855
-
856
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
857
- expect(definitionGenerator.openAPI.components.schemas.main.properties).to.have.property('error')
858
- expect(definitionGenerator.openAPI.components.schemas.main.properties.error).to.have.property('type')
859
- expect(definitionGenerator.openAPI.components.schemas.main.properties.error.type).to.be.equal('string')
860
- expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('definitions')
861
- expect(expected).to.equal('#/components/schemas/main')
862
-
863
- expect(spy.callCount).to.be.equal(1)
864
-
865
- spy.resetHistory()
866
- });
867
-
868
- it('should handle a schema that has been incorrectly dereferenced', async function() {
869
- const definitionGenerator = new DefinitionGenerator(mockServerless)
870
-
871
- const complexSchema = {
872
- $schema: 'http://json-schema.org/draft-04/schema#',
873
- title: 'JSON API Schema',
874
- $ref: '#/definitions/Error',
875
- definitions: {
876
- Error: {
877
- type: 'string'
878
- }
879
- }
880
- }
881
-
882
- const spy = sinon.spy(definitionGenerator, 'dereferenceSchema')
883
-
884
- const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
885
- .catch((err) => {
886
- console.error(err)
887
- })
888
-
889
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
890
- expect(definitionGenerator.openAPI.components.schemas.main).to.have.property('type')
891
- expect(definitionGenerator.openAPI.components.schemas.main.type).to.be.equal('string')
892
- expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('$schema')
893
- expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('$definitions')
894
- expect(expected).to.equal('#/components/schemas/main')
895
-
896
- expect(spy.callCount).to.be.equal(2)
897
-
898
- spy.resetHistory()
899
- });
900
-
901
- it('should handle a complex schema that has been incorrectly dereferenced', async function() {
902
- const definitionGenerator = new DefinitionGenerator(mockServerless)
903
-
904
- const complexSchema = {
905
- $schema: 'http://json-schema.org/draft-04/schema#',
906
- title: 'JSON API Schema',
907
- $ref: '#/definitions/Person',
908
- definitions: {
909
- Person: {
910
- type: 'object',
911
- properties: {
912
- name: {
913
- type: 'string'
914
- },
915
- age: {
916
- type: 'number'
917
- }
918
- }
919
- }
920
- }
921
- }
922
-
923
- const spy = sinon.spy(definitionGenerator, 'dereferenceSchema')
924
-
925
- const expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
926
- .catch((err) => {
927
- console.error(err)
928
- })
929
-
930
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
931
- expect(definitionGenerator.openAPI.components.schemas.main).to.have.property('type')
932
- expect(definitionGenerator.openAPI.components.schemas.main.type).to.be.equal('object')
933
- expect(definitionGenerator.openAPI.components.schemas.main).to.have.property('properties')
934
- expect(definitionGenerator.openAPI.components.schemas.main.properties).to.have.property('name')
935
- expect(definitionGenerator.openAPI.components.schemas.main.properties).to.have.property('age')
936
- expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('$schema')
937
- expect(definitionGenerator.openAPI.components.schemas.main).to.not.have.property('$definitions')
938
- expect(expected).to.equal('#/components/schemas/main')
939
-
940
- expect(spy.callCount).to.be.equal(2)
941
-
942
- spy.resetHistory()
943
- });
944
-
945
- it('should add all schemas from a conversion to the components', async function() {
946
- const complexSchema = {
947
- "$schema": "http://json-schema.org/draft-04/schema#",
948
- "title": "JSON API Schema",
949
- "description": "This is a blah blah for responses in the JSON API format. For more, see http://jsonapi.org",
950
- "type": "object",
951
- "properties": {
952
- "street_address": {
953
- "type": "string"
954
- },
955
- "country": {
956
- "type": "string",
957
- "default": "United States of America",
958
- "enum": [
959
- "United States of America",
960
- "Canada"
961
- ]
962
- }
963
- },
964
- "if": {
965
- "properties": {
966
- "country": {
967
- "const": "United States of America"
968
- }
969
- }
970
- },
971
- "then": {
972
- "properties": {
973
- "postal_code": {
974
- "pattern": "[0-9]{5}(-[0-9]{4})?"
975
- }
976
- }
977
- }
978
- }
979
-
980
- const definitionGenerator = new DefinitionGenerator(mockServerless)
981
- let expected = await definitionGenerator.schemaCreator(complexSchema, 'main')
982
- .catch((err) => {
983
- console.error(err)
984
- })
985
-
986
- expect(expected).to.equal('#/components/schemas/main')
987
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('main')
988
- expect(Object.keys(definitionGenerator.openAPI.components.schemas).length).to.be.equal(2)
989
-
990
- });
991
- });
992
-
993
- describe('schemas that are urls', () => {
994
- it('should attempt to download a schema and convert it', async function() {
995
- const simpleSchema = 'https://google.com/build/LicensedMember.json'
996
- const LicensedMemberJSON = require('../json/complex.json')
997
-
998
- const scope = nock('https://google.com')
999
- .get('/build/LicensedMember.json')
1000
- .reply(200, LicensedMemberJSON)
1001
-
1002
- const definitionGenerator = new DefinitionGenerator(mockServerless)
1003
- const expected = await definitionGenerator.schemaCreator(simpleSchema, 'LicensedMember')
1004
- .catch((err) => {
1005
- console.error(err)
1006
- })
1007
-
1008
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
1009
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('log')
1010
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('template')
1011
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('database')
1012
- expect(expected).to.equal('#/components/schemas/LicensedMember')
1013
- });
1014
-
1015
- it('should take a mix of schemas', async function() {
1016
- const complexSchema = 'https://google.com/build/LicensedMember.json'
1017
- const LicensedMemberJSON = require('../json/complex.json')
1018
-
1019
- const scope = nock('https://google.com')
1020
- .get('/build/LicensedMember.json')
1021
- .reply(200, LicensedMemberJSON)
1022
-
1023
- const definitionGenerator = new DefinitionGenerator(mockServerless)
1024
- let expected = await definitionGenerator.schemaCreator(complexSchema, 'LicensedMember')
1025
- .catch((err) => {
1026
- console.error(err)
1027
- })
1028
-
1029
- // this will fail validation due to a missing definition
1030
- const simpleSchema = {
1031
- type: "object",
1032
- properties: {
1033
- UUID: {
1034
- $ref: "#/definitions/log"
1035
- },
1036
- name: {
1037
- type: "string"
1038
- }
1039
- },
1040
- definitions: {}
1041
- }
1042
-
1043
- expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
1044
- .catch((err) => {
1045
- expect(err).to.be.an('error')
1046
- console.error(err)
1047
- })
1048
-
1049
- expect(expected).to.be.undefined
1050
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
1051
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('log')
1052
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('template')
1053
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.properties).to.have.property('database')
1054
- });
1055
-
1056
- it('should throw an error when a url can not be resolved', async function() {
1057
- const simpleSchema = 'https://google.com/build/LicensedMember.json'
1058
-
1059
- const scope = nock('https://google.com')
1060
- .get('/build/LicensedMember.json')
1061
- .reply(404)
1062
-
1063
- const definitionGenerator = new DefinitionGenerator(mockServerless)
1064
- const expected = await definitionGenerator.schemaCreator(simpleSchema, 'simpleSchema')
1065
- .catch((err) => {
1066
- expect(err).to.be.an('error')
1067
- })
1068
-
1069
- expect(expected).to.be.undefined
1070
- });
1071
-
1072
- it('should handle a poorly dereferenced schema', async function() {
1073
- const simpleSchema = 'https://google.com/build/LicensedMember.json'
1074
-
1075
- const externalSchema = {
1076
- $schema: 'http://json-schema.org/draft-04/schema#',
1077
- title: 'JSON API Schema',
1078
- $ref: '#/definitions/Error',
1079
- definitions: {
1080
- Error: {
1081
- type: 'string'
1082
- }
1083
- }
1084
- }
1085
-
1086
- const scope = nock('https://google.com')
1087
- .get('/build/LicensedMember.json')
1088
- .reply(200, externalSchema)
1089
-
1090
-
1091
- const definitionGenerator = new DefinitionGenerator(mockServerless)
1092
- const expected = await definitionGenerator.schemaCreator(simpleSchema, 'LicensedMember')
1093
- .catch((err) => {
1094
- console.error(err)
1095
- })
1096
-
1097
- expect(definitionGenerator.openAPI.components.schemas).to.have.property('LicensedMember')
1098
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember).to.have.property('type')
1099
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember.type).to.be.equal('string')
1100
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember).to.not.have.property('$schema')
1101
- expect(definitionGenerator.openAPI.components.schemas.LicensedMember).to.not.have.property('$definitions')
1102
- expect(expected).to.equal('#/components/schemas/LicensedMember')
1103
- });
1104
- });
1105
- });
1106
629
  });