BFD OpenAPI Docs

Overview

BFD uses the OpenAPI Specification, which is an interface description for APIs so users can learn about the capabilities of a service. We use them so consumers of the BFD API can quickly find and understand the API's capabilities and quickly integrate with it, possibly using automated tools to generate client code and test cases.

Generating BFD Server Docs

BFD has a flag in the form of a maven property apidocgen.skip that controls the execution of the generation of all of bfd-server-docs. By default, the maven property skips the generation. You can find the property being used in the pom file under the apps directory and in the pom file under the bfd-server-war directory. The artifacts are only generated in 3 cases:

• When explicitly requested by contributors during normal development by setting -Dapidocgen.skip to false (i.e. mvn clean install -DskipITs -DskipTests=true -Dmaven.build.cache.enabled=false -Dapidocgen.skip=false)
• When evaluating change sets in the CI process
• When creating a release

When generated, the BFD server documents like the data dictionaries and the Open API documents for version 1 and 2 of the BFD API are written to the dist directory of the project. As for the Open API documents, the file names are 'V1-OpenAPI-.yaml' and 'V2-OpenAPI-.yaml' where is the semantic version derived from the project version defined in the pom.xml.

For more information on the OpenAPI Specification see reference.