Swagger 是一套基于 OpenAPI 规范(OpenAPI Specification,OAS)构建的开源工具,后来成为了 Open API 标准的主要定义者,现在最新的版本为17年发布的 Swagger3(Open Api3)。 国内绝大部分人还在用过时的swagger2(17年停止维护并更名为swagger3) 对于 Rest API 来说很重要的一部分内容就是文档,Swagger 为我们提供了一套通过代码和注解自动生成文档的方法,这一点对于保证API 文档的及时性将有很大的帮助。 OAS本身是一个API规范,它用于描述一整套API接口,包括一个接口是哪种请求方式、哪些参数、哪些header等,都会被包括在这个文件中。它在设计的时候通常是YAML格式,这种格式书写起来比较方便,而在网络中传输时又会以json形式居多,因为json的通用性比较强。 SpringFox是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger2 集成到 Spring 中。
<!--引入Swagger3-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
package com.tms.tblog.infrastructure.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30).apiInfo(
new ApiInfoBuilder()
.title("Swagger2接口项目")
// 创建人信息
.version("1.0")
// 描述
.description("API接口")
.build()
);
}
}
package com.tms.tblog;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
@SpringBootApplication
@MapperScan("com.tms.tblog.dao")
@EnableWebMvc
public class TBlogApplication {
public static void main(String[] args) {
SpringApplication.run(TBlogApplication.class, args);
}
}
/**
* 账户控制
*/
@Api(tags = "账户接口")
@RequestMapping("/Account")
@RestController
@Log4j2
public class AccountController {
@Resource
private AccountService accountService;
/**
* 获取所有账户信息
*
* @return
*/
@ApiOperation(value = "获取账户接口")
@RequestMapping(value = "getAccount", method = RequestMethod.GET)
public List<Account> getAccount() {
List<Account> list = accountService.getAccount();
return list;
}
}
swagger3 | 注解位置 |
---|---|
@Api(tags=“接口描述”) | controller类上 |
@Operation(summary = “接口方法描述”) | controller 方法上 |
@ApiModelProperty(value = “字段描述”) | JavaBean的字段上 |
@ApiModel(“实体类的描述”) | JavaBean上 |
@EnableOpenApi | 配置类上 |
@ApiImplicitParams | controller的方法参数中 |
@ApiImplicitParam | @ApiImplicitParams 下的的子参数 |
@Parameter(description = “参数描述”) | controller 方法的参数中 |