Skip to content

Commit 6abf213

Browse files
author
Michał Błotniak
committed
Fix OpenAPI file and add apidoc target in Makefile
Change-Id: I69a5d3fa327ee96f0edc74df724bbe617b3b3cb9 Closes-Jira-Bug: CEM-4215
1 parent 4776252 commit 6abf213

File tree

5 files changed

+109
-35
lines changed

5 files changed

+109
-35
lines changed

‎Makefile

+22-2
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ CONTRAIL_API_CLIENT_REPO := contrail-api-client
33
BUILD_DIR := ../build
44
SRC_DIRS := cmd pkg vendor
55
DB_FILES := gen_init_mysql.sql gen_init_psql.sql init_data.yaml
6+
67
ifdef ANSIBLE_DEPLOYER_REPO_DIR
78
export ANSIBLE_DEPLOYER_REPO_DIR
89
else
@@ -70,12 +71,15 @@ generate_pb_go: generate_go pkg/models/gen_model.pb.go pkg/services/baseservices
7071

7172
generate: fast_generate format_gen
7273

74+
CONTRAIL_OPENAPI_PATH=public/openapi.json
75+
CONTRAIL_APIDOC_PATH=public/doc/index.html
76+
7377
generate_go:
7478
# Generate for contrail resources.
7579
@mkdir -p public/
7680
go run cmd/contrailschema/main.go generate \
7781
--schemas schemas/contrail --templates tools/templates/contrail/template_config.yaml \
78-
--schema-output public/schema.json --openapi-output public/openapi.json
82+
--schema-output public/schema.json --openapi-output $(CONTRAIL_OPENAPI_PATH)
7983
# Generate for openstack api resources.
8084
@mkdir -p public/neutron
8185
go run cmd/contrailschema/main.go generate \
@@ -193,12 +197,28 @@ else
193197
cp -r $(CONTRAIL_API_CLIENT_REPO_DIR) $(BUILD_DIR)/docker/contrail_go/$(CONTRAIL_API_CLIENT_REPO)
194198
endif
195199

196-
docker: docker_prepare ## Generate Docker files
200+
docker: apidoc docker_prepare ## Generate Docker files
197201
docker build --build-arg GOPATH=$(GOPATH) -t "contrail-go" $(BUILD_DIR)/docker/contrail_go
198202

199203
help: ## Display help message
200204
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
201205

206+
$(CONTRAIL_OPENAPI_PATH):
207+
$(MAKE) generate_go
208+
209+
$(CONTRAIL_APIDOC_PATH): $(CONTRAIL_OPENAPI_PATH)
210+
ifeq (, $(shell which spectacle))
211+
$(info No spectacle in $(PATH) consider installing it. Running in docker.)
212+
docker run --rm -v $(SOURCEDIR):/go node:10.15.3-alpine sh -c \
213+
"npm install --unsafe-perm -g [email protected] && spectacle -1 -t $(PWD)/$(dir $(CONTRAIL_APIDOC_PATH)) $(PWD)/$(CONTRAIL_OPENAPI_PATH)"
214+
else
215+
mkdir -p $(dir $(CONTRAIL_APIDOC_PATH))
216+
spectacle -1 -t $(dir $(CONTRAIL_APIDOC_PATH)) $(CONTRAIL_OPENAPI_PATH)
217+
endif
218+
219+
220+
apidoc: $(CONTRAIL_APIDOC_PATH)
221+
202222
.DEFAULT_GOAL := help
203223

204224
.PHONY: docker_prepare docker generate_go

‎README.md

+12
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,18 @@ Run all tests with coverage:
113113
make test
114114
```
115115

116+
## API documentation
117+
118+
OpenAPI specification file is generated during every run of `make generate` and it is located in `./public/openapi.json`.
119+
120+
You can also run API doc server on local machine using:
121+
122+
```bash
123+
make apidoc
124+
```
125+
126+
The doc will be available on [localhost:5000](http://localhost:5000).
127+
116128
## How to contribute
117129

118130
- Follow [Openstack review process](https://docs.openstack.org/infra/manual/developers.html)

‎pkg/schema/openapi.go

+73-27
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
2020
Produces: []string{"application/json"},
2121
Info: &spec.Info{
2222
InfoProps: spec.InfoProps{
23-
Version: "4.0",
23+
Version: "5.1",
2424
Title: "Contrail API OpenAPI2.0 Definitions",
2525
License: &spec.License{
2626
Name: "Apache2.0",
@@ -42,18 +42,19 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
4242
// add reference and back ref
4343

4444
for _, reference := range apiSchema.References {
45-
referenceSchema := spec.Schema{
45+
referenceSchema := &spec.Schema{
4646
SchemaProps: spec.SchemaProps{
47-
Description: reference.Description,
4847
Properties: map[string]spec.Schema{
4948
"uuid": {
5049
SchemaProps: spec.SchemaProps{
51-
Type: spec.StringOrArray([]string{"string"}),
50+
Description: "UUID of the referenced resource.",
51+
Type: spec.StringOrArray([]string{"string"}),
5252
},
5353
},
5454
"to": {
5555
SchemaProps: spec.SchemaProps{
56-
Type: spec.StringOrArray([]string{"array"}),
56+
Description: "FQName of the referenced resource.",
57+
Type: spec.StringOrArray([]string{"array"}),
5758
Items: &spec.SchemaOrArray{
5859
Schema: &spec.Schema{
5960
SchemaProps: spec.SchemaProps{
@@ -66,30 +67,38 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
6667
},
6768
},
6869
}
69-
var ref spec.Ref
70-
ref, err = spec.NewRef("#/definitions/" + reference.RefType)
71-
if err != nil {
72-
return nil, err
73-
}
7470
if reference.RefType != "" {
71+
var ref spec.Ref
72+
ref, err = spec.NewRef("#/definitions/" + reference.RefType)
73+
if err != nil {
74+
return nil, err
75+
}
7576
referenceSchema.Properties["attr"] = spec.Schema{
7677
SchemaProps: spec.SchemaProps{
7778
Ref: ref,
7879
},
7980
}
8081
}
81-
d.Properties[reference.LinkTo.ID+"_ref"] = referenceSchema
82+
d.Properties[reference.LinkTo.ID+"_refs"] = spec.Schema{
83+
SchemaProps: spec.SchemaProps{
84+
Description: reference.Description,
85+
Type: spec.StringOrArray([]string{"array"}),
86+
Items: &spec.SchemaOrArray{
87+
Schema: referenceSchema,
88+
},
89+
},
90+
}
8291
}
8392

84-
for _, backref := range apiSchema.Children {
93+
for _, child := range apiSchema.Children {
8594
var ref spec.Ref
86-
ref, err = spec.NewRef("#/definitions/" + backref.LinkTo.JSONSchema.GoName + "APIType")
95+
ref, err = spec.NewRef("#/definitions/" + child.LinkTo.JSONSchema.GoName + "APIType")
8796
if err != nil {
8897
return nil, err
8998
}
90-
d.Properties[backref.LinkTo.ID+"s"] = spec.Schema{
99+
d.Properties[child.LinkTo.ID+"s"] = spec.Schema{
91100
SchemaProps: spec.SchemaProps{
92-
Description: backref.Description,
101+
Description: child.Description,
93102
Type: spec.StringOrArray([]string{"array"}),
94103
Items: &spec.SchemaOrArray{
95104
Schema: &spec.Schema{
@@ -119,6 +128,16 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
119128

120129
pathItem := spec.PathItem{
121130
PathItemProps: spec.PathItemProps{
131+
Parameters: []spec.Parameter{
132+
{
133+
SimpleSchema: spec.SimpleSchema{Type: StringType},
134+
ParamProps: spec.ParamProps{
135+
Name: "id",
136+
Required: true,
137+
In: "path",
138+
},
139+
},
140+
},
122141
Get: &spec.Operation{
123142
OperationProps: spec.OperationProps{
124143
//TODO Parameters:
@@ -198,6 +217,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
198217
Parameters: []spec.Parameter{
199218
{
200219
ParamProps: spec.ParamProps{
220+
Name: apiSchema.TypeName,
201221
Required: true,
202222
In: "body",
203223
Schema: &spec.Schema{
@@ -260,6 +280,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
260280
Parameters: []spec.Parameter{
261281
{
262282
ParamProps: spec.ParamProps{
283+
Name: apiSchema.TypeName,
263284
In: "body",
264285
Required: true,
265286
Schema: &spec.Schema{
@@ -317,6 +338,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
317338
OperationProps: spec.OperationProps{
318339
Parameters: []spec.Parameter{
319340
{
341+
SimpleSchema: spec.SimpleSchema{Type: StringType},
320342
ParamProps: spec.ParamProps{
321343
In: "query",
322344
Name: "parent_id",
@@ -325,6 +347,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
325347
},
326348
},
327349
{
350+
SimpleSchema: spec.SimpleSchema{Type: StringType},
328351
ParamProps: spec.ParamProps{
329352
In: "query",
330353
Name: "parent_fq_name_str",
@@ -333,6 +356,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
333356
},
334357
},
335358
{
359+
SimpleSchema: spec.SimpleSchema{Type: StringType},
336360
ParamProps: spec.ParamProps{
337361
In: "query",
338362
Name: "pobj_uuids",
@@ -341,6 +365,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
341365
},
342366
},
343367
{
368+
SimpleSchema: spec.SimpleSchema{Type: StringType},
344369
ParamProps: spec.ParamProps{
345370
In: "query",
346371
Name: "detail",
@@ -349,6 +374,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
349374
},
350375
},
351376
{
377+
SimpleSchema: spec.SimpleSchema{Type: StringType},
352378
ParamProps: spec.ParamProps{
353379
In: "query",
354380
Name: "back_ref_id",
@@ -357,22 +383,25 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
357383
},
358384
},
359385
{
386+
SimpleSchema: spec.SimpleSchema{Type: StringType},
360387
ParamProps: spec.ParamProps{
361388
In: "query",
362389
Name: "page_marker",
363-
Description: "Pagenation start marker",
390+
Description: "Pagination start marker",
364391
Required: false,
365392
},
366393
},
367394
{
395+
SimpleSchema: spec.SimpleSchema{Type: StringType},
368396
ParamProps: spec.ParamProps{
369397
In: "query",
370398
Name: "page_limit",
371-
Description: "Pagenation limit",
399+
Description: "Pagination limit",
372400
Required: false,
373401
},
374402
},
375403
{
404+
SimpleSchema: spec.SimpleSchema{Type: StringType},
376405
ParamProps: spec.ParamProps{
377406
In: "query",
378407
Name: "count",
@@ -381,14 +410,16 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
381410
},
382411
},
383412
{
413+
SimpleSchema: spec.SimpleSchema{Type: StringType},
384414
ParamProps: spec.ParamProps{
385415
In: "query",
386416
Name: "fields",
387-
Description: " Comma separated object field list you are interested in",
417+
Description: "Comma separated object field list you are interested in",
388418
Required: false,
389419
},
390420
},
391421
{
422+
SimpleSchema: spec.SimpleSchema{Type: StringType},
392423
ParamProps: spec.ParamProps{
393424
In: "query",
394425
Name: "shared",
@@ -397,6 +428,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
397428
},
398429
},
399430
{
431+
SimpleSchema: spec.SimpleSchema{Type: StringType},
400432
ParamProps: spec.ParamProps{
401433
In: "query",
402434
Name: "filters",
@@ -405,6 +437,7 @@ func (api *API) ToOpenAPI() (*spec.Swagger, error) {
405437
},
406438
},
407439
{
440+
SimpleSchema: spec.SimpleSchema{Type: StringType},
408441
ParamProps: spec.ParamProps{
409442
In: "query",
410443
Name: "exclude_hrefs",
@@ -532,24 +565,37 @@ func (s *JSONSchema) ToOpenAPI() (*spec.Schema, error) {
532565
}
533566
properties[key] = *p
534567
}
535-
return &spec.Schema{
568+
result := &spec.Schema{
536569
SchemaProps: spec.SchemaProps{
537-
ID: s.ID,
538570
Description: s.Description,
539-
Type: spec.StringOrArray([]string{s.Type}),
571+
Type: spec.StringOrArray([]string{typeToOpenAPI(s.Type)}),
540572
Title: s.Title,
541573
//TODO(nati) support this.
542574
//Format: s.Format,
543575
//Maximum: s.Maximum,
544576
//Minimum: s.Minimum,
545577
//Pattern: s.Pattern,
546578
//Enum: s.Enum,
547-
Default: s.Default,
548-
Required: s.Required,
549-
Items: &spec.SchemaOrArray{
550-
Schema: items,
551-
},
579+
Default: s.Default,
580+
Required: s.Required,
552581
Properties: properties,
553582
},
554-
}, nil
583+
}
584+
585+
if items != nil {
586+
result.Items = &spec.SchemaOrArray{
587+
Schema: items,
588+
}
589+
}
590+
591+
return result, nil
592+
}
593+
594+
func typeToOpenAPI(t string) string {
595+
switch t {
596+
case UintType:
597+
return IntegerType
598+
default:
599+
return t
600+
}
555601
}

‎pkg/schema/schema.go

+1-5
Original file line numberDiff line numberDiff line change
@@ -396,11 +396,7 @@ func (s *JSONSchema) resolveSQLForArray(
396396
}
397397
var bind string
398398
if s.GoType != "" {
399-
if s.IsUint() {
400-
bind = sqlBindMap[UintType]
401-
} else {
402-
bind = sqlBindMap[s.Type]
403-
}
399+
bind = sqlBindMap[s.Type]
404400
}
405401

406402
*columns = append(*columns, &ColumnConfig{

‎playbooks/contrail-go-docker/run.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
- name: Run tests and linters on the source code in parallel
4040
command: make -j test lint
4141
- name: Generate Docker files
42-
command: make ANSIBLE_DEPLOYER_BRANCH={{ zuul.branch }} CONTRAIL_API_CLIENT_BRANCH={{ zuul.branch }} docker
42+
command: make SOURCEDIR={{ sourcedir }} ANSIBLE_DEPLOYER_BRANCH={{ zuul.branch }} CONTRAIL_API_CLIENT_BRANCH={{ zuul.branch }} docker
4343

4444
- name: Fix files ownerships
4545
file:

0 commit comments

Comments
 (0)