Swagger 文档工具 设计、构建、文档化和使用您的 RESTful API ...

北冰洋以北  金牌会员 | 2024-5-15 19:14:35 | 显示全部楼层 | 阅读模式
打印 上一主题 下一主题
楼主

主题 908|帖子 908|积分 2724

Swagger

Swagger 是一个功能强大的开源框架，支持大量工具生态系统，帮助您设计、构建、文档化和使用您的 RESTful API。
使用 SpringBoot

您可以从 swagger-springboot 获取完整的项目演示。
springboot-blog 中文版
文件结构可能如下所示：
  1. .
  2. |____main
  3. | |____java
  4. | | |____com
  5. | | | |____ryo
  6. | | | | |____Application.java
  7. | | | | |____controller
  8. | | | | | |____HelloWorld.java
  9. | | | | |____Swagger2.java
  10. | |____resources
  11. | | |____application.properties
  12. | | |____log4j2.xml
  13. | | |____README.md
复制代码
maven 配置

1、 创建 SpringBoot 项目

  • 在 pom.xml 中导入 SpringBoot 依赖包
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  3.     <modelVersion>4.0.0</modelVersion>
  5.     <groupId>com.ryo</groupId>
  6.     <artifactId>springboot</artifactId>
  7.     <version>1.0.0</version>
  9.     <properties>
  10.         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  11.         <plugin.tomcat.version>2.2</plugin.tomcat.version>
  12.         <maven-surefire-plugin.version>2.18.1</maven-surefire-plugin.version>
  13.         <maven-compiler-plugin.version>3.3</maven-compiler-plugin.version>
  15.         
  16.         <spring-boot.version>1.3.5.RELEASE</spring-boot.version>
  18.         <log4j.version>2.6</log4j.version>
  19.     </properties>
  21.     <dependencies>
  22.         
  23.         <dependency>
  24.             <groupId>org.springframework.boot</groupId>
  25.             <artifactId>spring-boot-starter-web</artifactId>
  26.             <version>${spring-boot.version}</version>
  27.         </dependency>
  28.         <dependency>
  29.             <groupId>org.springframework.boot</groupId>
  30.             <artifactId>spring-boot-starter-test</artifactId>
  31.             <version>${spring-boot.version}</version>
  32.         </dependency>
  34.         
  35.         <dependency>
  36.             <groupId>org.apache.logging.log4j</groupId>
  37.             <artifactId>log4j-api</artifactId>
  38.             <version>${log4j.version}</version>
  39.         </dependency>
  40.         <dependency>
  41.             <groupId>org.apache.logging.log4j</groupId>
  42.             <artifactId>log4j-core</artifactId>
  43.             <version>${log4j.version}</version>
  44.         </dependency>
  46.     </dependencies>
  49.     <build>
  50.         <plugins>
  51.             <plugin>
  52.                 <groupId>org.springframework.boot</groupId>
  53.                 <artifactId>spring-boot-maven-plugin</artifactId>
  54.                 <version>${spring-boot.version}</version>
  55.             </plugin>
  57.             <plugin>
  58.                 <groupId>org.apache.maven.plugins</groupId>
  59.                 <artifactId>maven-surefire-plugin</artifactId>
  60.                 <version>${maven-surefire-plugin.version}</version>
  61.                 <configuration>
  62.                     <skipTests>true</skipTests>
  63.                     <testFailureIgnore>true</testFailureIgnore>
  64.                 </configuration>
  65.             </plugin>
  67.             <plugin>
  68.                 <groupId>org.apache.maven.plugins</groupId>
  69.                 <artifactId>maven-compiler-plugin</artifactId>
  70.                 <version>${maven-compiler-plugin.version}</version>
  71.                 <configuration>
  72.                     <source>1.8</source>
  73.                     <target>1.8</target>
  74.                 </configuration>
  75.             </plugin>
  76.         </plugins>
  77.     </build>
  78. </project>
复制代码
2、maven 导入 jar
  1. <dependency>
  2.     <groupId>io.springfox</groupId>
  3.     <artifactId>springfox-swagger2</artifactId>
  4.     <version>2.2.2</version>
  5. </dependency>
  6. <dependency>
  7.     <groupId>io.springfox</groupId>
  8.     <artifactId>springfox-swagger-ui</artifactId>
  9.     <version>2.2.2</version>
  10. </dependency>
复制代码
配置信息

我们可以定义一个 swagger 的全局配置。
  1. package com.github.houbb.register.http.admin.config;
  3. import org.springframework.context.annotation.Bean;
  4. import org.springframework.context.annotation.Bean;
  5. import org.springframework.context.annotation.Configuration;
  6. import springfox.documentation.builders.ApiInfoBuilder;
  7. import springfox.documentation.builders.PathSelectors;
  8. import springfox.documentation.builders.RequestHandlerSelectors;
  9. import springfox.documentation.service.Contact;
  10. import springfox.documentation.spi.DocumentationType;
  11. import springfox.documentation.spring.web.plugins.Docket;
  12. import springfox.documentation.swagger2.annotations.EnableSwagger2;
  14. /**
  15. * swagger 配置
  16. *
  17. * @author binbin.hou
  18. * @since 1.0.0
  19. */
  20. @EnableSwagger2
  21. @Configuration
  22. public class SwaggerConfig {
  24.     @Bean
  25.     public Docket createRestApi() {
  26.         return new Docket(DocumentationType.SWAGGER_2)
  27.                 .pathMapping("/")
  28.                 .select()
  29.                 .apis(RequestHandlerSelectors.basePackage("com.github.houbb.register.http.admin.controller"))
  30.                 .paths(PathSelectors.any())
  31.                 .build()
  32.                 .apiInfo(new ApiInfoBuilder()
  33.                         .title("SpringBoot整合Swagger测试")
  34.                         .description("SpringBoot整合Swagger，详细信息......")
  35.                         .version("9.0")
  36.                         .contact(new Contact("老马", "blog.csdn.net", "aaa@gmail.com"))
  37.                         .license("The Apache License")
  38.                         .licenseUrl("http://www.baidu.com")
  39.                         .build());
  40.     }
  42. }
复制代码
最焦点的主要是 RequestHandlerSelectors.basePackage("com.github.houbb.register.http.admin.controller")
我们指定了需要扫描的包路径。
文档定义

3、配置使用

  • Application.java
  1. package com.ryo;
  3. import org.springframework.boot.SpringApplication;
  4. import org.springframework.boot.autoconfigure.SpringBootApplication;
  6. /**
  7. * Created by houbinbin on 16/6/5.
  8. */
  9. @SpringBootApplication
  10. public class Application {
  11.     public static void main(String args[]) {
  12.         SpringApplication.run(Application.class, args);
  13.     }
  14. }
复制代码

  • HelloWorld.java
  1. package com.ryo.controller;
  3. import io.swagger.annotations.Api;
  4. import io.swagger.annotations.ApiOperation;
  5. import org.springframework.web.bind.annotation.RequestMapping;
  6. import org.springframework.web.bind.annotation.RequestMethod;
  7. import org.springframework.web.bind.annotation.RestController;
  9. /**
  10. * Created by houbinbin on 16/6/19.
  11. */
  12. @RestController
  13. @RequestMapping("hello")
  14. @Api(value = "hello", description = "spring boot 初步测试")
  15. public class HelloWorld {
  17.     @ApiOperation(value="hello", notes="初步使用啦啦啦")
  18.     @RequestMapping(method = RequestMethod.GET)
  19.     public String hello() {
  20.         return "SUCCESS";
  21.     }
  22. }
复制代码

  • application.properties
  1. server.port=180080
复制代码
应用启动 & 访问

4、 启动应用
Maven Projects->${project}->lugins->spring-boot->spring-boot:run
  1. .   ____          _            __ _ _
  2. /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
  3. ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
  4. \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  5.   '  |____| .__|_| |_|_| |_\__, | / / / /
  6. =========|_|==============|___/=/_/_/_/
  7. :: Spring Boot ::        (v1.3.5.RELEASE)
  9. 2016-12-25 15:29:50.066  INFO 4095 --- [           main] com.ryo.Application                      : Starting Application on houbinbindeMacBook-Pro.local with PID 4095 (/Users/houbinbin/IT/code/springboot/target/classes started by houbinbin in /Users/houbinbin/IT/code/springboot)
  10. 2016-12-25 15:29:50.069  INFO 4095 --- [           main] com.ryo.Application                      : No active profile set, falling back to default profiles: default
  11. ...
  12. 2016-12-25 15:29:52.688  INFO 4095 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 18080 (http)
  13. 2016-12-25 15:29:52.692  INFO 4095 --- [           main] com.ryo.Application                      : Started Application in 3.094 seconds (JVM running for 5.262)
复制代码

  • 欣赏器访问
欣赏器访问：http://localhost:8080/swagger-ui.html
基本配置例子

Controller 控制器
  1. package com.github.houbb.register.http.admin.controller;
  4. import com.github.houbb.register.http.admin.model.ClientLogDto;
  5. import io.swagger.annotations.Api;
  6. import io.swagger.annotations.ApiOperation;
  7. import org.springframework.web.bind.annotation.PostMapping;
  8. import org.springframework.web.bind.annotation.RequestMapping;
  10. import org.springframework.stereotype.Controller;
  11. import org.springframework.web.bind.annotation.ResponseBody;
  13. /**
  14. * <p>
  15. * 客户端数据日志 前端控制器
  16. * </p>
  17. *
  18. * @author binbin.hou
  19. * @since 2021-03-08
  20. */
  21. @Controller
  22. @RequestMapping("/clientLog")
  23. @Api(tags = "客户端日志 CRUD")
  24. public class ClientLogController {
  26.     @PostMapping("/add")
  27.     @ApiOperation("添加日志")
  28.     @ResponseBody
  29.     public String add(ClientLogDto clientLogDto) {
  30.         System.out.println(clientLogDto);
  31.         return "ok";
  32.     }
  34. }
复制代码
实体属性

针对入参 ClientLogDto，我们可以添加对应的属性形貌如下：
  1. public class ClientLogDto implements Serializable {
  3.     @ApiModelProperty(value = "类型")
  4.     private String type;
  6.     @ApiModelProperty(value = "地址")
  7.     private String ip;
  9.     @ApiModelProperty(value = "名称")
  10.     private String name;
  12.     //getter & setter & toString()
  13. }
复制代码
效果

重新启动应用，效果如下：

测试

我们可以使用 【Try it out】，可以进行相关的测试。

点击 execute 按钮，可以获取非常详细的文档返回。
常用注解阐明


  • @Api注解可以用来标志当前Controller的功能。
  • @ApiOperation注解用来标志一个方法的作用。
  • @ApiImplicitParam注解用来形貌一个参数，可以配置参数的中文寄义，也可以给参数设置默认值，如许在接口测试的时候可以避免手动输入。
  • 假如有多个参数，则需要使用多个@ApiImplicitParam注解来形貌，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
  • 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能取代@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略。
  • 假如参数是一个对象（比方上文的更新接口），对于参数的形貌也可以放在实体类中。
一点思考

swagger2 的 ui 还是非常惬意的，功能也比较强大，不外有一点比较惋惜，那就是注解显得有一点点冗余。
可以思量共同 yAPI 使用。
参考资料

SpringBoot的整合（四、整合Swagger2）
SpringBoot swagger 配置账号密码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。

本帖子中包含更多资源

您需要 登录 才可以下载或查看，没有账号？立即注册

x
回复

使用道具 举报

0 个回复

倒序浏览
返回列表

快速回复

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 or 立即注册

本版积分规则

北冰洋以北

金牌会员
这个人很懒什么都没写!

楼主热帖

标签云

存储 服务器
微信订阅号
微信服务号
微信客服
小程序
H5
关于我们 商务合作 网站地图
©Copyright 2022-2024 杭州祥升科技有限公司 版权所有 浙ICP备20004199号
快速回复 返回顶部 返回列表