SpringBoot整合Swagger2的步骤详解

时间：2021-12-31 14:56:26

简介

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础， 对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

springfox大致原理:

springfox的大致原理就是，在项目启动的过种中，spring上下文在初始化的过程， 框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类， 并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，并生成对应的文档描述数据.该数据是json格式，通过路径：项目地址/ v2/api-docs可以访问到该数据，然后swaggerUI根据这份数据生成相应的文档描述界面。 因为我们能拿到这份数据，所以我们也可以生成自己的页面.

SpringBoot整合Swagger2

引入依赖

  1. <dependency>
  2. <groupId>io.springfox</groupId>
  3. <artifactId>springfox-swagger2</artifactId>
  4. <version>2.7.0</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>io.springfox</groupId>
  8. <artifactId>springfox-swagger-ui</artifactId>
  9. <version>2.7.0</version>
  10. </dependency>

注意：jdk1.8以上才能运行swagger2

编写配置类配置Swagger

  1. @Configuration
  2. @EnableSwagger2
  3. public class SwaggerConfig{
  4. @Bean
  5. public Docket createRestApi() {
  6. return new Docket(DocumentationType.SWAGGER_2)
  7. .apiInfo(apiInfo())
  8. .select()
  9. .apis(RequestHandlerSelectors.basePackage("org.example.yourproject"))//这里填写项目package
  10. .paths(PathSelectors.any())
  11. .build();
  12. }//springfox为我们提供了一个Docket（摘要的意思）类，我们需要把它做成一个Bean注入到spring中， 显然，我们需要一个配置文件，并通过一种方式（显然它会是一个注解）告诉程序，这是一个Swagger配置文件。
  13.  
  14. private ApiInfo apiInfo() {
  15. return new ApiInfoBuilder()
  16. .title("Spring Boot中使用Swagger2构建RESTful API")
  17. .description("rest api 文档构建利器")
  18. .termsOfServiceUrl("https://www.cnblogs.com/yrxing/")
  19. .contact("xing")
  20. .version("1.0")
  21. .build();
  22. }
  23.  
  24. }//springfox允许我们将信息组合成一个ApiInfo的类，作为构造参数传给Docket

SpringBoot整合Swagger2的步骤详解

SpringBoot整合Swagger2的步骤详解

访问：http://localhost:{your_server_port}/swagger-ui.html

Swagger2常用注解使用

SpringBoot整合Swagger2的步骤详解

@Api()、@ApiOperation()

  1. @RestController
  2. @RequestMapping(value = "/user", produces = APPLICATION_JSON_VALUE) //配置返回值 application/json
  3. @Api(tags = "用户管理")
  4. public class HelloController {
  5.  
  6. ArrayList<User> users = new ArrayList<>();
  7.  
  8. @ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
  9. @RequestMapping(value = {""}, method = RequestMethod.GET)
  10. public List<User> hello() {
  11. users.add(new User("逻辑", "luoji"));
  12. users.add(new User("叶文杰", "yewenjie"));
  13. return users;
  14. }
  15. }

@ApiModel()、@ApiModelProperty()

  1. @ApiModel(description = "用户",value = "用户")
  2. public class User {
  3.  
  4. private String id;
  5.  
  6. @ApiModelProperty(value = "用户名")//value属性指明了该字段的含义(描述 Description)
  7. private String username;
  8.  
  9. @ApiModelProperty(hidden = true)//此注解可以作用在字段或者方法上,只要 hidden 属性为 true ,该字段或者方法就不会被生成api文档.
  10. private String password;
  11.  
  12. private String email;
  13.  
  14. private Integer age;
  15.  
  16. private Boolean enabled;
  17.  
  18. }

@ApiParam()

  1. @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
  2. @RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
  3.  
  4. public User getUser(@ApiParam(naeme = "id",value = "用户id", required = true) @PathVariable(value = "id") String id) {
  5. return new User(id, "itguang", "123456");
  6. }//@ApiParam这个注解,需要注意的是,这个注解方法的参数前面,不能直接用在方法上面.

@ApiImplicitParams()、@ApiImplicitparam()

  1. ···
  2. @Api("测试用例1")
  3. @Controller
  4. public class swaggerTestUse(){
  5. @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
  6. @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入参", required = true, dataType = "Integer", paramType = "query"),
  7. @ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
  8. })
  9. public void apiOperationSwaggerTest(Integer id, Brand band){
  10. }
  11. }

以上就是SpringBoot整合Swagger2的步骤详解的详细内容，更多关于SpringBoot整合Swagger2的资料请关注服务器之家其它相关文章！

原文链接：https://www.cnblogs.com/yrxing/p/14651341.html

标签：

相关文章