Springfox: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 56: Line 56:
=Generating Swagger/OpenAPI Specification from Spring Code with Springfox=
=Generating Swagger/OpenAPI Specification from Spring Code with Springfox=


{{External|https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/}}
==General Considerations==
{{External|http://springfox.github.io/springfox/docs/current/}}


==General Considerations==
Written based on:
* https://springframework.guru/spring-boot-restful-api-documentation-with-swagger-2/
* http://springfox.github.io/springfox/docs/current/


<font color=darkgray>How is the artifact generated? Where?</font>
<font color=darkgray>How is the artifact generated? Where?</font>

Revision as of 22:19, 14 February 2019

External

Internal

Overview

Springfox is a suite of Java libraries for automating the generation of machine and human readable specification for JSON APIs written with Spring Framework. Springfox works by examining an application, once, at runtime to infer API semantics based on Spring configurations, class structure and various compile time java annotations.

Dependencies

repositories {

   jcenter()
}

dependencies {

    implementation "io.springfox:springfox-swagger2:2.9.2"
}

Essential Classes

Docket

springfox.documentation.spring.web.plugins.Docket: the primary API configuration mechanism.

ApiSelectorBuilder

ApiSelectorBuilder provides fine grained control over the endpoints exposed via swagger.

Annotations

Security Schemas

The following security schemas are available to protect the API:

  • ApiKey
  • BasicAuth
  • OAuth

Models

Non-reachable Model

A model that should be described in the generated specification but is not explicitly used in any operation.

Generating Swagger/OpenAPI Specification from Spring Code with Springfox

General Considerations

Written based on:

How is the artifact generated? Where?

Generating the Swagger Specification

At this point, only the "io.springfox:springfox-swagger2" dependency is needed. This dependency contains all the functionality Springfox needs to generate the specification in the JSON format.

There are two essential code changes:

1. Annotate the Spring Boot application class, or a Configuration with @EnableSwagger2.

2. Expose a configured Docket instance as a bean.

If these two elements are present, the Spring application will generate its JSON-formatted. Swagger2 specification while invoked as: http://localhost:8080/v2/api-docs

UI Support

dependencies {

    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}