一, 简单介绍
Swagger 是一个实现了 OpenAPI(OpenAPI Specification) 规范的工具集. OpenAPI 是 Linux 基金会的一个项目, 试图通过定义一种用来描述 API 格式或 API 定义的语言, 来规范 RESTful 服务开发过程.
swagger 大大方便了前后端开发人员, 用过的人都说好. 但是也有一些人并未体验过 swagger, 还在苦苦的手写接口文档, 麻烦又不规范; 还有一些人虽然用过, 但是只是朦朦胧胧, 看别人怎么用直接就 CV 过来用了, 使用的很碎片, 不系统. 我之前就是这个样子, 只知道添加个依赖, 启动项目后访问: localhost:8080/swagger-ui.html, 就能看到生成的文档了, 很是简单.
一次我看到生成的文档上总是多出来一个 basic-error-controller, 强迫症犯了, 就想要把它弄掉, 于是顺便看了下 swagger 的配置, 在这里记录一下.
官网: https://swagger.io/
看官方的说明:
Swagger 包含的工具集:
Swagger 编辑器: Swagger Editor 允许您在浏览器中编辑 YAML 中的 OpenAPI 规范并实时预览文档.
Swagger UI: Swagger UI 是 HTML,JavaScript 和 CSS 资产的集合, 可以从符合 OAS 标准的 API 动态生成漂亮的文档.
Swagger Codegen: 允许根据 OpenAPI 规范自动生成 API 客户端库 (SDK 生成), 服务器存根和文档.
Swagger Parser: 用于解析来自 Java 的 OpenAPI 定义的独立库
Swagger Core: 与 Java 相关的库, 用于创建, 使用和使用 OpenAPI 定义
Swagger Inspector(免费): API 测试工具, 可让您验证您的 API 并从现有 API 生成 OpenAPI 定义
SwaggerHub(免费和商业): API 设计和文档, 为使用 OpenAPI 的团队构建.
二, 入门案例
SpringBoot 已经集成了 Swagger, 使用简单注解即可生成 swagger 的 API 文档.
1. 引入依赖
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>2.9.2</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>2.9.2</version>
- </dependency>
2. 编写配置
- @Configuration
- @EnableSwagger2 // Swagger 的开关, 表示已经启用 Swagger
- public class SwaggerConfig {
- @Bean
- public Docket API() {
- Docket docket = new Docket(DocumentationType.SWAGGER_2)
- .host("localhost:8081")// 不配的话, 默认当前项目端口
- .apiInfo(apiInfo())
- .pathMapping("/")
- .select() // 选择哪些路径和 API 会生成 document
- .apis(RequestHandlerSelectors.any())// 对所有 API 进行监控
- // .apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 选择监控的 package
- // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只监控有 ApiOperation 注解的接口
- // 不显示错误的接口地址
- .paths(Predicates.not(PathSelectors.regex("/error.*")))// 错误路径不监控
- .paths(PathSelectors.regex("/.*"))// 对根下所有路径进行监控
- .build();
- return docket;
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder().title("XXXX 项目接口文档")
- .contact(new Contact("Hanstrovsky", "www.hanstrovsky.com", "Hanstrovsky@gmail.com"))
- .description("这是用 Swagger 动态生成的接口文档")
- .termsOfServiceUrl("NO terms of service")
- .license("The Apache License, Version 2.0")
- .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
- .version("1.0")
- .build();
- }
- }
3. 启动测试
启动服务, 访问: http://localhost:8081/swagger-ui.HTML
就能看到 swagger-ui 为我们提供的 API 页面了:
可以看到我们编写的接口, 任意点击一个, 即可看到接口的详细信息:
可以看到详细的接口声明, 包括:
请求方式:
请求路径
请求参数
响应等信息
点击右上角的 try it out! 还可以测试接口.
三, 常用注解
刚才的文档说明中, 是 swagge-ui 根据接口自动生成, 不够详细. 如果有需要, 可以通过注解自定义接口声明. 常用的注解包括:
/**
@API: 修饰整个类, 描述 Controller 的作用
@ApiOperation: 描述一个类的一个方法, 或者说一个接口
@ApiParam: 单个参数描述
@ApiModel: 用对象来接收参数
@ApiProperty: 用对象接收参数时, 描述对象的一个字段
@ApiResponse:HTTP 响应其中 1 个描述
@ApiResponses:HTTP 响应整体描述
@ApiIgnore: 使用该注解忽略这个 API
@ApiError : 发生错误返回的信息
@ApiImplicitParam: 一个请求参数
@ApiImplicitParams: 多个请求参数
*/
示例:
- @PostMapping("/people")
- @ApiOperation(value = "保存人员信息")
- @ApiResponses({
- @ApiResponse(code = 0, message = "保存成功"),
- @ApiResponse(code = 1, message = "保存失败")
- })
- public FrontResult save(
- @ApiParam(value = "保存参数", example = "")
- @RequestBody People people) {
- people.setBirthday(Timestamp.valueOf(LocalDateTime.now()));
- return new FrontResult(FrontResult.SUCCEED, "保存成功", peopleDao.save(people));
- }
- @Data
- @ApiModel(description = "人员信息保存请求对象")
- public class People {
- @ApiModelProperty(value = "人员编号")
- private Long id;
- @ApiModelProperty(value = "姓名", required = true,position = 1)
- private String name;
- @ApiModelProperty(value = "性别", required = true,position = 2)
- private String sex;
- @ApiModelProperty(value = "生日", required = true,position = 3)
- @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
- private Timestamp birthday;
- }
查看文档:
四, 美化一下
如果觉得用起来不太习惯, 可以用 Swagger-Bootstrap-UI 替换 Swagger 默认的 UI 实现左右菜单风格的 Swagger-UI , 让其看起来更清晰明了.
1. 添加依赖
- <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
- <dependency>
- <groupId>com.GitHub.xiaoymin</groupId>
- <artifactId>swagger-Bootstrap-ui</artifactId>
- <version>1.9.6</version>
- </dependency>
2. 重启项目
访问 http://localhost:8080/doc.HTML :
来源: https://www.cnblogs.com/hanstrovsky/p/12725112.html