Last year, I created Personal development application called Settlement-kun, but I didn't create the backend API specification, so let's quickly create it using OpenAPI (Swagger). I came to use it. I will touch on the introduction method at that time and the settings that I personally care about.
The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.
(Translation) The OpenAPI Specification is a specification of machine-readable interface files for describing, generating, consuming, and visualizing RESTful web services.
From wikipedia
So, to put it simply, OpenAPI is an interface for creating specifications for RESTful Web services (API, etc.). Originally the name was Swagger, but it seems that the name has changed to Open API because it was donated to OAI (Open API Initiative) established by Microsoft/Google/IBM on December 31, 2015. SmartBear Software, the creator of Swagger, also participated in OAI, and it seems that it was donated. However, since OpenAPI has not yet become popular as a name, there are still people and articles that call it Swagger.
There are several ways to introduce OpenAPI into Spring Boot.
Among them, this time we will introduce using SpringFox
.
SpringFox
is a library of Spring Framework that can create OpenAPI-based specification documents.
https://github.com/springfox/springfox
Describe the following description in build.gradle.
build.gradle
~abridgement~
dependencies {
compile("io.springfox:springfox-swagger2:${Version of your choice}")
compile("io.springfox:springfox-swagger-ui:${Version of your choice}")
~abridgement~
}
For $ {your favorite version}
, specify the version you want to use. The version that can be specified in the link below and its usage rate are described.
springfox-swagger2 springfox-swagger-ui
Use the AutoConfigure function of SpringBoot to load the settings. Create the following Configure class.
SwaggerConf.java
package com.dededesignworkshop.seisankun_api.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConf {
@Bean
public Docket swaggerPlugin() {
return new Docket(DocumentationType.SWAGGER_2) // SWAGGER_12, SWAGGER_2, SWAGGER_I have a WEB but I don't really know which one is better
.select() //Generate ApiSelectorBuilder
.apis(RequestHandlerSelectors.any()) //Set the RequestHandler that is the target of the document
.paths(PathSelectors.regex("/v1.*")) //Set the target path of the document
.build();
}
}
A class called Docket is defined as a bean. The official document is here, so please take a look at the other setting items as well.
When you access the path of /swagger-ui.html
, the following will be displayed.
There is no problem with the above Bean definition as the minimum setting, but there are many other customizations, so I tried it.
You can set basic API information with apiInfo () of Docket. This is the red frame part of the image.
Add the following to the Configure class above.
SwaggerConf.java
~abridgement~
@Configuration
@EnableSwagger2
public class SwaggerConf {
@Bean
public Docket swaggerPlugin() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.regex("/v1.*"))
.build()
.apiInfo(getApiInfo()); //API basic information setting with ApiInfo type
}
private ApiInfo getApiInfo() {
return new ApiInfoBuilder()
.title("Seisankun-api")
.description("Travel split calculation app\"Liquidation\"API")
.version("1.0.0")
.contact(new Contact("nooboolean","webSiteUrl","email"))
.build();
}
}
The official document is here, so please see other setting items as well.
By defining a bean that returns the UiConfiguration class in UiConfigurationBuilder, detailed settings for each endpoint can be made. You can set the following screens.
Add the following to the Configure class above.
SwaggerConf.java
~abridgement~
@Configuration
@EnableSwagger2
public class SwaggerConf {
~abridgement~
@Bean
public UiConfiguration swaggerUiConf() {
return UiConfigurationBuilder.builder()
.displayRequestDuration(true)
.defaultModelExpandDepth(3)
.defaultModelRendering(ModelRendering.EXAMPLE)
.filter(true)
.operationsSorter(OperationsSorter.METHOD)
.validatorUrl("")
.docExpansion(DocExpansion.LIST)
.build();
}
}
Details of the items set this time.
Setting items | Explanation |
---|---|
displayRequestDuration | RequestDuration when API is executed on OpenAPI(Response time)You can set whether or not to display. |
defaultModelExpandDepth | The structure of the specific value of the response described in the details of Responses(Model)When writing, you can set up to what level you want to keep it open without folding. |
defaultModelRendering | The default notation of the specific value of the response described in the details of Responses should be "Example of value" or "Structure".(Model)You can choose whether to set it to. |
filter | You can set the need for filter fields that allow you to filter endpoints. |
operationsSorter | You can set the order of the endpoints. This time, the order of methods is used. |
docExpansion | You can set how far the hierarchical endpoint display opens by default. |
validatorUrl | You can set validationUrl. By disablinglike thisYou can avoid the problem. |
The official document is here, so please take a look at the other setting items as well.
You can write a description of what role each endpoint plays. This is possible by annotating the method of each endpoint with ApiOperation.
UserController.java
@ApiOperation(value = "Refer to the user list associated with travel", notes = "Refers to the user list associated with the travel ID specified in the parameter")
public List<User> findByTravelId(@PathVariable("travel_id") Integer travel_id) {
return this.userService.findByTravelId(travel_id);
}
The display results are as follows.
There seems to be more customization, so I will add it each time I customize it additionally! !!
Recommended Posts