swagger,中文“拽”的意思。它是一個功能強大的api框架,它的集成非常簡單,不僅提供了在線文檔的查閱,而且還提供了在線文檔的測試。另外swagger很容易構建restful風格的api,簡單優雅帥氣,正如它的名字。
一、引入依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
二、寫配置類
package com.elvis.web.swagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.elvis.web"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger構建api文檔")
.description("簡單優雅的restfun風格,https://blog.csdn.net/JackRen_Developer")
.termsOfServiceUrl("https://blog.csdn.net/JackRen_Developer")
.version("1.0")
.build();
}
}
通過@Configuration註解,表明它是一個配置類,@EnableSwagger2開啓swagger2。apiINfo()配置一些基本的信息。apis()指定掃描的包會生成文檔。
三、寫生產文檔的註解
swagger通過註解表明該接口會生成文檔,包括接口名、請求方法、參數、返回信息的等等。
@Api:修飾整個類,描述Controller的作用
@ApiOperation:描述一個類的一個方法,或者說一個接口
@ApiParam:單個參數描述
@ApiModel:用對象來接收參數
@ApiProperty:用對象接收參數時,描述對象的一個字段
@ApiResponse:HTTP響應其中1個描述
@ApiResponses:HTTP響應整體描述
@ApiIgnore:使用該註解忽略這個API
@ApiError :發生錯誤返回的信息
@ApiParamImplicitL:一個請求參數
@ApiParamsImplicit 多個請求參數
現在通過一個例子來說明:
package com.elvis.web;
import com.elvis.interfaces.UserService;
import com.elvis.pojo.User;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import javax.annotation.Resource;
import java.util.List;
/**
* @program: fbs
* @description:
* @author: JackRen
* @create: 2019-09-19 11:24
**/
@Controller
public class UserController {
@Resource
private UserService userService;
@RequestMapping(value = "/user/query",method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "查詢用戶信息", notes="根據url來獲取詳細信息")
public List<User> queryUsers()
{
return userService.queryUsers();
}
@RequestMapping(value = "/user/search",method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "查詢用戶信息", notes="根據url來獲取數據庫詳細信息")
public List<User> queryUsersDB()
{
return userService.queryUsersDB();
}
}
通過相關注解,就可以讓swagger2生成相應的文檔。如果你不需要某接口生成文檔,只需要在加@ApiIgnore註解即可。需要說明的是,如果請求參數在url上,@ApiImplicitParam 上加paramType = “path” 。
啓動工程,訪問:http://localhost:8080/swagger-ui.html ,就看到swagger-ui:
至此,swagger集成結束!