From aaea309bd5e850711ddc955a074c76d75a4653ac Mon Sep 17 00:00:00 2001 From: Romain Beuque <556072+rbeuque74@users.noreply.github.com> Date: Wed, 13 Apr 2022 15:37:37 +0200 Subject: [PATCH] feat(spec): add SetSecuritySchemes to declare the securitySchemes in the specification (#77) feat(spec): add SetSecuritySchemes method (#77) Add the SetSecuritySchemes method to the Generator type to allows the configuration of the spec's security schemes. Signed-off-by: Romain Beuque <556072+rbeuque74@users.noreply.github.com> Co-authored-by: William Poussier --- README.md | 41 ++++++++++++++++++++++++++++++++++++++++- openapi/generator.go | 6 ++++++ openapi/spec.go | 2 +- 3 files changed, 47 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1b4a27b..17a988d 100644 --- a/README.md +++ b/README.md @@ -223,7 +223,7 @@ You can use additional tags. Some will be interpreted by *tonic*, others will be | `description` | Add a description of the field in the spec. | | `deprecated` | Indicates if the field is deprecated. Accepted values are `1`, `t`, `T`, `TRUE`, `true`, `True`, `0`, `f`, `F`, `FALSE`. Invalid value are considered to be false. | | `enum` | A coma separated list of acceptable values for the parameter. | -| `example` | An example value to be used in OpenAPI specification. See [section below](#Providing-Examples-for-Custom-Types) for the demonstration on how to provide example for custom types. | +| `example` | An example value to be used in OpenAPI specification. See [section below](#Providing-Examples-for-Custom-Types) for the demonstration on how to provide example for custom types. | | `format` | Override the format of the field in the specification. Read the [documentation](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypeFormat) for more informations. | | `validate` | Field validation rules. Read the [documentation](https://godoc.org/gopkg.in/go-playground/validator.v8) for more informations. | | `explode` | Specifies whether arrays should generate separate parameters for each array item or object property (limited to query parameters with *form* style). Accepted values are `1`, `t`, `T`, `TRUE`, `true`, `True`, `0`, `f`, `F`, `FALSE`. Invalid value are considered to be false. | @@ -276,6 +276,45 @@ f.GET("/openapi.json", nil, f.OpenAPI(infos, "json")) ``` **NOTE**: The generator will never panic. However, it is strongly recommended to call `fizz.Errors` to retrieve and handle the errors that may have occured during the generation of the specification before starting your API. +#### Servers information + +If the OpenAPI specification refers to an API that is not hosted on the same domain, or using a path prefix not included in the spec, you will have to declare server information. This can be achieved using the `f.Generator().SetServers` method. + +```go +f := fizz.New() +f.Generator().SetServers([]*openapi.Server{ + { + Description: "Fruits Market - production", + URL: "https://example.org/api/1.0", + }, +}) +``` + +#### Security schemes + +If your API requires authentication, you have to declare the security schemes that can be used by the operations. This can be achieved using the `f.Generator().SetSecuritySchemes` method. + +```go +f := fizz.New() +f.Generator().SetSecuritySchemes(map[string]*openapi.SecuritySchemeOrRef{ + "apiToken": { + SecurityScheme: &openapi.SecurityScheme{ + Type: "apiKey", + In: "header", + Name: "x-api-token", + }, + }, +}) +``` + +Once defined, the security schemes will be available for all operations. You can override them on an per-operation basis using the `fizz.Security()` function. + +```go +fizz.Security(&openapi.SecurityRequirement{ + "apiToken": []string{}, +}) +``` + #### Components The output types of your handlers are registered as components within the generated specification. By default, the name used for each component is composed of the package and type name concatenated using _CamelCase_ style, and does not contain the full import path. As such, please ensure that you don't use the same type name in two eponym package in your application. diff --git a/openapi/generator.go b/openapi/generator.go index 465228f..5b0c1cf 100644 --- a/openapi/generator.go +++ b/openapi/generator.go @@ -110,6 +110,12 @@ func (g *Generator) SetSecurityRequirement(security []*SecurityRequirement) { g.api.Security = security } +// SetSecuritySchemes sets the security schemes that can be used +// inside the operations of the specification. +func (g *Generator) SetSecuritySchemes(security map[string]*SecuritySchemeOrRef) { + g.api.Components.SecuritySchemes = security +} + // API returns a copy of the internal OpenAPI object. func (g *Generator) API() *OpenAPI { cpy := *g.api diff --git a/openapi/spec.go b/openapi/spec.go index deece33..33475b1 100644 --- a/openapi/spec.go +++ b/openapi/spec.go @@ -16,7 +16,7 @@ type OpenAPI struct { } // Components holds a set of reusable objects for different -// ascpects of the specification. +// aspects of the specification. type Components struct { Schemas map[string]*SchemaOrRef `json:"schemas,omitempty" yaml:"schemas,omitempty"` Responses map[string]*ResponseOrRef `json:"responses,omitempty" yaml:"responses,omitempty"`