api.go

package dsl

import (
	"goa.design/goa/v3/eval"
	"goa.design/goa/v3/expr"
)

// API defines a network service API. It provides the API name, description and other global
// properties. There may only be one API declaration in a given design package.
//
// API is a top level DSL. API takes two arguments: the name of the API and the
// defining DSL.
//
// The API properties are leveraged by the OpenAPI specification. The server
// expressions are also used by the server and the client tool code generators.
//
// Example:
//
//	var _ = API("adder", func() {
//	    Title("title")                // Title used in documentation
//	    Description("description")    // Description used in documentation
//	    Version("2.0")                // Version of API
//	    TermsOfService("terms")       // Terms of use
//	    Contact(func() {              // Contact info
//	        Name("contact name")
//	        Email("contact email")
//	        URL("contact URL")
//	    })
//	    License(func() {              // License
//	        Name("license name")
//	        URL("license URL")
//	    })
//	    Docs(func() {                 // Documentation links
//	        Description("doc description")
//	        URL("doc URL")
//	    })
//	    Server("addersvr", func() {
//	        Host("development", func() {
//	            URI("http://localhost:80")
//	            URI("grpc://localhost:8080")
//	        })
//	    })
//	}
func API(name string, fn func()) *expr.APIExpr {
	if name == "" {
		eval.ReportError("API first argument cannot be empty")
		return nil
	}
	if _, ok := eval.Current().(eval.TopExpr); !ok {
		eval.IncompatibleDSL()
		return nil
	}
	expr.Root.API = expr.NewAPIExpr(name, fn)
	return expr.Root.API
}

// Title sets the API title. It is used by the generated OpenAPI specification.
//
// Title must appear in a API expression.
//
// Title accepts a single string argument.
//
// Example:
//
//	var _ = API("divider", func() {
//	    Title("divider API")
//	})
func Title(val string) {
	if s, ok := eval.Current().(*expr.APIExpr); ok {
		s.Title = val
		return
	}
	eval.IncompatibleDSL()
}

// Version specifies the API version. One design describes one version.
//
// Version must appear in a API expression.
//
// Version accepts a single string argument.
//
// Example:
//
//	var _ = API("divider", func() {
//	    Version("1.0")
//	})
func Version(ver string) {
	if s, ok := eval.Current().(*expr.APIExpr); ok {
		s.Version = ver
		return
	}
	eval.IncompatibleDSL()
}

// Contact sets the API contact information.
//
// Contact must appear in a API expression.
//
// Contact takes a single argument which is the defining DSL.
//
// Example:
//
//	var _ = API("divider", func() {
//	    Contact(func() {
//	        Name("support")
//	        Email("support@goa.design")
//	        URL("https://goa.design")
//	    })
//	})
func Contact(fn func()) {
	contact := new(expr.ContactExpr)
	if !eval.Execute(fn, contact) {
		return
	}
	if a, ok := eval.Current().(*expr.APIExpr); ok {
		a.Contact = contact
		return
	}
	eval.IncompatibleDSL()
}

// License sets the API license information.
//
// License must appear in a API expression.
//
// License takes a single argument which is the defining DSL.
//
// Example:
//
//	var _ = API("divider", func() {
//	    License(func() {
//	        Name("MIT")
//	        URL("https://github.com/goadesign/goa/blob/master/LICENSE")
//	    })
//	})
func License(fn func()) {
	license := new(expr.LicenseExpr)
	if !eval.Execute(fn, license) {
		return
	}
	if a, ok := eval.Current().(*expr.APIExpr); ok {
		a.License = license
		return
	}
	eval.IncompatibleDSL()
}

// Randomizer sets the API example randomizer.
//
// Randomizer must appear in a API expression.
//
// Randomizer takes a single argument which is an implementation of
// expr.Randomizer.
//
// The default randomizer uses the API name as the seed, to get consistent
// random examples.
//
// Example:
//
//	var _ = API("divider", func() {
//	    Randomizer(expr.NewFakerRandomizer("different seed"))
//	})
//
// There's also a deterministic randomizer which will only generate one example
// for each type, so all strings are "abc123", all ints are 1, etc.
//
// Example:
//
//	var _ = API("divider", func() {
//	    Randomizer(expr.NewDeterministicRandomizer())
//	})
func Randomizer(randomizer expr.Randomizer) {
	if s, ok := eval.Current().(*expr.APIExpr); ok {
		s.ExampleGenerator = &expr.ExampleGenerator{Randomizer: randomizer}
		return
	}
	eval.IncompatibleDSL()
}

// Docs provides external documentation URLs. It is used by the generated
// OpenAPI specification.
//
// Docs must appear in an API, Service, Method or Attribute expr.
//
// Docs takes a single argument which is the defining DSL.
//
// Example:
//
//	var _ = API("cellar", func() {
//	    Docs(func() {
//	        Description("Additional documentation")
//	        URL("https://goa.design")
//	    })
//	})
func Docs(fn func()) {
	docs := new(expr.DocsExpr)
	if !eval.Execute(fn, docs) {
		return
	}
	switch e := eval.Current().(type) {
	case *expr.APIExpr:
		e.Docs = docs
	case *expr.ServiceExpr:
		e.Docs = docs
	case *expr.MethodExpr:
		e.Docs = docs
	case *expr.AttributeExpr:
		e.Docs = docs
	case *expr.HTTPFileServerExpr:
		e.Docs = docs
	default:
		eval.IncompatibleDSL()
	}
}

// TermsOfService describes the API terms of services or links to them.
//
// TermsOfService must appear in a API expression.
//
// TermsOfService takes a single argument which is the TOS text or URL.
//
// Example:
//
//	var _ = API("github", func() {
//	    TermsOfService("https://help.github.com/articles/github-terms-of-API/"
//	})
func TermsOfService(terms string) {
	if s, ok := eval.Current().(*expr.APIExpr); ok {
		s.TermsOfService = terms
		return
	}
	eval.IncompatibleDSL()
}

// Name sets the contact or license name.
//
// Name must appear in a Contact or License expression.
//
// Name takes a single argument which is the contact or license name.
//
// Example:
//
//	var _ = API("divider", func() {
//	    License(func() {
//	        Name("MIT")
//	        URL("https://github.com/goadesign/goa/blob/master/LICENSE")
//	    })
//	})
func Name(name string) {
	switch def := eval.Current().(type) {
	case *expr.ContactExpr:
		def.Name = name
	case *expr.LicenseExpr:
		def.Name = name
	default:
		eval.IncompatibleDSL()
	}
}

// Email sets the contact email.
//
// Email must appear in a Contact expression.
//
// Email takes a single argument which is the email address.
//
// Example:
//
//	var _ = API("divider", func() {
//	    Contact(func() {
//	        Email("support@goa.design")
//	    })
//	})
func Email(email string) {
	if c, ok := eval.Current().(*expr.ContactExpr); ok {
		c.Email = email
	}
}

// URL sets the contact, license or external documentation URL.
//
// URL must appear in Contact, License or Docs.
//
// URL accepts a single argument which is the URL.
//
// Example:
//
//	Docs(func() {
//	    URL("https://goa.design")
//	})
func URL(url string) {
	switch def := eval.Current().(type) {
	case *expr.ContactExpr:
		def.URL = url
	case *expr.LicenseExpr:
		def.URL = url
	case *expr.DocsExpr:
		def.URL = url
	default:
		eval.IncompatibleDSL()
	}
}