v3 programmatic interface

[arthurdm]

[Updated based on Leo's comments]

interface OpenAPIController

OpenAPIConfig bootstrap();

where bootstrap() can be used to return an OpenAPIConfig object which encapsulates all configurations (for Reader, Scanner, OpenAPI, etc) along with a predefined OpenAPI definition (optional) to start-off (similar to beforeScan in v2).

OpenAPIConfig class will have getters and setters for configurable items:

getOpenAPI()
setOpenAPI(OpenAPI)
getClasses()
setClasses(Set<Class<?>>)
isScan()
setScan(boolean)
getFilterClass()
setFilterClass(String)
isPrettyPrint()
setPrettyPrint(boolean)
getIgnoredRoutes()
setIgnoredRoutes(Collection)

[leochr]

After more discussion, we think it's better to further simplify the interface.

interface OpenAPIController

• OpenAPIConfig bootstrap();

where bootstrap() can be used to return an OpenAPIConfig object which encapsulates all configurations (for Reader, Scanner, OpenAPI, etc) along with a predefined OpenAPI definition (optional) to start-off (similar to beforeScan in v2).

OpenAPIConfig class will have getters and setters for configurable items:

getOpenAPI()
setOpenAPI(OpenAPI)
getClasses()
setClasses(Set<Class<?>>)
isScan()
setScan(boolean)
getFilterClass()
setFilterClass(String)
isPrettyPrint()
setPrettyPrint(boolean)
getIgnoredRoutes()
setIgnoredRoutes(Collection)
.....
.....

All setters will return the OpenAPIConfig back to allow users to set more configurations easily.

OpenAPIConfig should ideally only use exposed classes / interfaces and avoid using internal / heavy-lifting classes (more dependency), so it can be exposed to users easily.

Any other methods that needs to be invoked by Reader/Scanner can be added to OpenAPIController. Dropped 'afterScan' method, since it seems users can instead use the OpenAPIConfig to control the generated OpenAPI definition (by setting which packages / classes to scan / ignore) instead of overwriting the generated definition. @fehguy your thoughts?

[leochr]

A sample implementation of OpenAPIController :

public class OpenAPIControllerImpl implements OpenAPIController {

	@Override
	public OpenAPIConfig bootstrap() {
		return new OpenAPIConfig()
				.setOpenAPI(new OpenAPI()
						.info(new Info()
							.contact(new Contact()
			                        	.email("mail@sample.org")
			                        	.name("Sample Name")
			                        	.url("https://foo.bar")))
						.externalDocs(new ExternalDocumentation()
							.description("read more here")
							.url("http://swagger.io"))
						.addTagsItem(new Tag()
							.name("sample tag")
							.description("all about neat things")))
				.setFilterClass("com.sample.FilterClassImpl")
				.setScan(true)
				.setPrettyPrint(true);
	}
}

[fehguy]

Hi, looks good to me. For scanning, would you expect that the setClasses method would be used to provide a list of classes which should be scanned, and some "other helper" would determine that list of classes independently? So, a web.xml reader, for example, would scan for the appropriate classes (either by Swagger annotations or other), then call this configuration utility?

I think the only thing missing to me is how we trigger such logic. In the programmatic case, this should be sufficient, as long as we have a mechanism to provide packages or classes, by names (strings) for scanning.

[leochr]

The OpenAPIConfig will consolidate all configurations that can be specified by users. It's sole purpose would be to get the user settings to control the generated OpenAPI definition. We'll use default values for configurations not set by users.

The list of methods mentioned above are from existing interfaces (Scanner, ReaderConfig, SwaggerConfig, etc). We can modify the methods to make it easier for users to pass in the configuration values. I was thinking that the 'setClasses' method would be used by users to provide the classes to scan, so instead of list of Classes, we can accept packages and/or classes by names (strings) for scanning. If user didn't specify the classes, then we'll scan all.

Similar to ReaderListener in v2, we will find the user's implementation of OpenAPIController and invoke the bootstrap() method to get the OpenAPIConfig and then use its settings to scan and generate OpenAPI definition. In v2, I believe the implementations of ReaderListener had to be annotated in order for it to be found and its methods to be invoked (I could be wrong), but we should find the implementation of OpenAPIController even if it doesn't have any annotations. Unlike ReaderListener, which could have multiple implementations, we should only accept one implementation of OpenAPIController.

[arthurdm]

Update:

interface OpenAPIController
OpenAPIConfig bootstrap(Map<String,Object> environment);

interface OpenAPIConfig
getOpenAPI()
setOpenAPI(OpenAPI)
getClasses()
setClasses(Set<Class<?>>)
isScan()
setScan(boolean)
getFilterClass()
setFilterClass(String)
getUserDefinedOptions()
setUserDefinedOptions(Map<String,Object>

interface OpenAPIFilter
-> OAS version of https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-core/src/main/java/io/swagger/core/filter/SwaggerSpecFilter.java