msxswagger

README

MSX Swagger

https://github.com/CiscoDevNet/go-msx-swagger

Package CiscoDevNet/go-msx-swagger adds a Swagger interface to your MSX service. The main features are:

• expose a Swagger interface for your MSX service
• optionally secure access with MSX User Management Service integration
• supports OpenAPI 2.0 and 3.0 specifications

---

• Install
• Usage
• Public SSO Security Clients
• Unsecured Example
• Secured Example
• License

Install

With a correctly configured Go toolchain:

go get -u github.com/CiscoDevNet/go-msx-swagger

Usage

Using go-msx-swagger is simple:

1. Generate an OpenAPI specification for your service and save the resulting json to a file that can be accessed by your application. The default OpenAPI version is 3.0, but it can be controlled through configuration.

2. Import the package into your app.

3. Configure it and add a wild card route to your configured endpoint.

Public SSO Security Clients

Before you can secure your MSX Swagger documentation with msxswagger you will need to create a public SSO security client. First sign in to your MSX environment then either:

• open Settings->SSO Configurations->Add SSO Clients and add a new client, or
• use the MSX Swagger documentation for IDM Microservice->Security Clients->POST /idm/api/v2/clientsecurity.

This example payload is a good starting point, but be sure to change it meet your specific requirements.

{
    "clientId":"my-public-client",
    "grantTypes":[
        "refresh_token",
        "authorization_code"
    ],
    "maxTokensPerUser":-1,
    "useSessionTimeout":false,
    "resourceIds":[
    ],
    "scopes":[
        "address",
        "read",
        "phone",
        "openid",
        "profile",
        "write",
        "email"
    ],
    "autoApproveScopes":[
        "address",
        "read",
        "phone",
        "openid",
        "profile",
        "write",
        "email"
    ],
    "authorities":[
        "ROLE_USER",
        "ROLE_PUBLIC"
    ],
    "registeredRedirectUris":[
        "/**/swagger-sso-redirect.html"
    ],
    "accessTokenValiditySeconds":9000,
    "refreshTokenValiditySeconds":18000,
    "additionalInformation":{
    }
}

Unsecured Example

To add unsecured Swagger documentation create an OpenAPI 3.0 specification called swagger.json and save it to the same folder as your service binary. This Swagger documentation will be visible to anyone that can reach your MSX environment, even if they do not have user credentials.

// Create a new default msxswagger configuration.
c := msxswagger.NewDefaultSwaggerConfig()
// Disable security.
c.DocumentationConfig.Security.Enabled = false
// Configure the path to your specification file.
c.SwaggerJsonPath = "swagger.json"
// Configure the base context for your web application.
c.DocumentationConfig.RootPath = "/myservice"
// Create a new instance of msxswagger
s, _ := msxswagger.NewSwagger(c)
// Add it to your router as a wildcard path match to your configured Swagger 
// path (defaults to /swagger). In this example we are using a gorilla/mux router.
r.PathPrefix("/myservice/swagger/").HandlerFunc(s.SwaggerRoutes)

To use an older 2.0 spec simply add the following:

c.DocumentationConfig.SpecVersion = "2.0"

Secured Example

To secure your Swagger documentation using the MSX User Management Service configure msxswagger as shown. Users will then need to sign in to MSX to access Swagger.

// Create a new default msxswagger configuration.
c := msxswagger.NewDefaultSwaggerConfig()
// Enable security.
c.DocumentationConfig.Security.Enabled = true
// Configure the path to your MSX User Management Service. Your application must
// be served from the same FQDN or MSX will reject the OAuth redirect.
c.DocumentationConfig.Security.Sso.BaseUrl = "https://trn6-demo2.ciscovms.com/idm"
// Configure the path to your specification file.
c.SwaggerJsonPath = "swagger.json"
// Configure the base context for your web application.
c.DocumentationConfig.RootPath = "/myservice"
// Create a new instance of msxswagger.
s, _ := msxswagger.NewSwagger(c)
// Add it to your router as a wildcard path match to your configured Swagger 
// path (defaults to /swagger). In this example we are using a gorilla/mux router.
r.PathPrefix("/myservice/swagger/").HandlerFunc(s.SwaggerRoutes)

Once your app has started you can see your Swagger UI by going to the configured route. In a production solution you might want to pull dynamic configuration values from Vault or Consul.

Checkout the example directory for a simple working example.

License

MIT licensed. See the LICENSE file for details.

Documentation

Overview

Copyright (c) 2021 Cisco Systems, Inc and its affiliates All Rights reserved

Copyright (c) 2021 Cisco Systems, Inc and its affiliates All Rights reserved

Copyright (c) 2021 Cisco Systems, Inc and its affiliates All Rights reserved

Copyright (c) 2021 Cisco Systems, Inc and its affiliates All Rights reserved

Index

• type AppInfo
• type DocumentationConfig
• type MsxSwagger
  • func NewMsxSwagger(cfg *MsxSwaggerConfig) (*MsxSwagger, error)
  • func (p *MsxSwagger) SwaggerRoutes(w http.ResponseWriter, r *http.Request)
• type MsxSwaggerConfig
  • func NewDefaultMsxSwaggerConfig() *MsxSwaggerConfig
• type Security
• type Sso

Types

type AppInfo

type AppInfo struct {
	Name        string
	Description string
	Version     string
}

AppInfo describes the application

type DocumentationConfig

type DocumentationConfig struct {
	RootPath    string
	ApiPath     string `config:"default=/apidocs.json"`
	SwaggerPath string `config:"default=/swagger-resources"`
	SpecVersion string `config:"default=3.0.0"`
	Security    Security
	Ui          struct {
		Endpoint string `config:"default=/swagger"`
		View     string `config:"default=/swagger-ui.html"`
	}
}

DocumentationConfig is the config used to configure your swagger Key config elements are: RootPath is the base path your application is serving from defaults to / UI.Endpoint is the path you are serving swagger from defaults to /swagger and is concatinated with RootPath when accessing from the browser Security.Enabled flags Oauth on or off Security.Sso.BaseUrl is the path to MSX Usermanagment Service should be changed

type MsxSwagger

type MsxSwagger struct {
	// contains filtered or unexported fields
}

MsxSwagger contains all required information to serve a swagger page config is a pointer to a MsxSwaggerConfig spec is an openapi Swagger spec fileSystem is an http fileSystem

func NewMsxSwagger

func NewMsxSwagger(cfg *MsxSwaggerConfig) (*MsxSwagger, error)

NewMsxSwagger take a MsxSwaggerConfig and returns a MsxSwagger Object Will return an error if provided swagger.json file is not parsable

func (*MsxSwagger) SwaggerRoutes

func (p *MsxSwagger) SwaggerRoutes(w http.ResponseWriter, r *http.Request)

SwaggerRoutes is an http.Handlefunc that serves MsxSwagger As this function must handle multiple paths it must be served from a handler that supports wildcard paths mount path must match values configured in MsxSwagger config RootPath + UI.Endpoint

type MsxSwaggerConfig

type MsxSwaggerConfig struct {
	SwaggerJsonPath     string
	AppInfo             AppInfo
	DocumentationConfig DocumentationConfig
}

MsxSwaggerConfig represents a MsxSwagger config object SwaggerJsonPath is the path to your openapi json file.

func NewDefaultMsxSwaggerConfig

func NewDefaultMsxSwaggerConfig() *MsxSwaggerConfig

type Security

type Security struct {
	Enabled bool
	Sso     Sso
}

type Sso

type Sso struct {
	BaseUrl       string `config:"default=http://localhost:9103/idm"`
	TokenPath     string `config:"default=/v2/token"`
	AuthorizePath string `config:"default=/v2/authorize"`
	ClientId      string `config:"default="`
	ClientSecret  string `config:"default="`
}