API Documentation

Swagger generated documentation

[ 1 Official links ] [ 2 Swagger Java annotations ]

Official links

Swagger Core is a Java implementation of the OpenAPI Specification, described here.

Swagger Java annotations

Official documentation
Integration in Maven projects

Example of pom.xml to add swagger dependency and generate 3.0 OpenAPI documentation:

...
	<dependency>
		<groupId>javax.ws.rs</groupId>
		<artifactId>javax.ws.rs-api</artifactId>
		<version>2.1</version>
	</dependency>
	<dependency>
		<groupId>javax.servlet</groupId>
		<artifactId>javax.servlet-api</artifactId>
		<version>3.1.0</version>
	</dependency>
...
			<plugin>
				<groupId>io.swagger.core.v3</groupId>
				<artifactId>swagger-maven-plugin</artifactId>
				<version>2.2.28</version>
				<configuration>
					<outputFileName>openapi</outputFileName>
					<outputPath>${project.build.directory}/generated-api-test</outputPath>
					<outputFormat>JSONANDYAML</outputFormat>
					<resourcePackages>
						<package>com.cambyze.finance_api</package>
					</resourcePackages>
					<prettyPrint>TRUE</prettyPrint>
				</configuration>
				<executions>
					<execution>
						<phase>compile</phase>
						<goals>
							<goal>resolve</goal>
						</goals>
					</execution>
				</executions>
			</plugin>

@OpenAPIDefinition: To indicate to Swagger that the class is an API to be documented
- @Operation: REST method documentation.

Example:

@OpenAPIDefinition(
    info = @Info(title = "Cambyze banking service", version = "0.0",
        description = "Services to banking accounts",
        termsOfService = "https://cambyze.com/termsofservice/",
        license = @License(name = "Apache 2.0",
            url = "https://www.apache.org/licenses/LICENSE-2.0.html"),
        contact = @Contact(url = "https://cambyze.com/", name = "Cambyze support",
            email = "support@cambyze.com")),
    servers = {@Server(description = "Cambyze server", url = "https://cambyze.com/banking-api")})
@RestController
public class BankAccountController {
...
  @GET
  @Consumes("application/json")
  @Operation(summary = "Send the monthly bank statement",
      description = "Send the monthly bank statement for the date of today",
      requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
          description = "No request body needed, you have to use the required parameters: ban (the bank account number, ex: CAMBYZEBANK-2)",
          required = false),
      parameters = {@Parameter(required = true, description = "Bank Account Number",
          example = "CAMBYZEBANK-2")},
      responses = {@ApiResponse(description = "The bank statement",
          content = @Content(mediaType = "MonthlyBankStatement"))})

  @Path("/monthlyBankStatement")
  @GetMapping("/monthlyBankStatement")
  public MonthlyBankStatement calculateMonthlyBankStatement(
      @RequestParam(value = "ban") String ban) {

About other annotations, see Spring boot

Cambyze

API Documentation

Analytics

Official links

Swagger Java annotations

Related content