SpringBoot整合Swagger2API文档详细使用

快来打我* 2023-06-07 08:17 25阅读 0赞

### SpringBoot整合Swagger2API文档详细使用 ###

*   *   *   *  引言
             *  构建MAVEN工程
             *   *   *  创建maven project
                     *  引入pom依赖
                     *  创建swagger配置类
                     *  创建springboot启动类
                     *  启动工程，浏览器输入http://localhost:8080/swagger-ui.html
             *  整合Mybatis提供一个接口供于测试
             *   *   *  引入mybatis依赖
                     *  数据库SQL
                     *  配置YML文件
                     *  pojo类
                     *  mapper层
                     *  service层
                     *  controller层（根据Id查询User信息）
                     *  启动类加上扫mapper包的注解
                     *  启动项目地址栏输入\[http://localhost:8080/getById?id=1\](http://localhost:8080/getById?id=1)
                     *  运行\[http://localhost:8080/swagger-ui.html\](http://localhost:8080/swagger-ui.html)看有没有接口生产
                     *  改造controller层
                     *  再次输入\[http://localhost:8080/swagger-ui.html\](http://localhost:8080/swagger-ui.html)
                     *  最终工程结构展示
                     *  swagger的一些注解及参数说明

#### 引言 ####

> 本教程采用eclipse纯手动构建，望知悉。  
> swagger也称为Open API，Swagger从API文档中手动完成工作，并提供一系列用于生成，可视化和维护API文档的解决方案。简单的说就是一款让你更好的书写API文档的框架。我们为什么选择swagger，现在的网站开发结果越来越注重前后端的分离，比如以前的webFrom到现在的mvc模式都是为了这个前后端的分离。就算再如何的分离实现，也是不可避免的要进行数据交互的，那么接口的重要性就提现出来了。他成了前端和后端交互的重要途径，API文档也因此成了前端开发人员与后端开发人员的重要纽带。所有我们有一个API文档框架岂不是美哉。

#### 构建MAVEN工程 ####

###### 创建maven project ######

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70]

###### 引入pom依赖 ######

<parent>
    		<groupId>org.springframework.boot</groupId>
    		<artifactId>spring-boot-starter-parent</artifactId>
    		<version>2.0.0.RELEASE</version>
    	</parent>
    
    	<dependencies>
    		
    		<dependency>
    			<groupId>org.springframework.boot</groupId>
    			<artifactId>spring-boot-starter-web</artifactId>
    		</dependency>
    
    		
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger2</artifactId>
    			<version>2.4.0</version>
    		</dependency>
    		<dependency>
    			<groupId>io.springfox</groupId>
    			<artifactId>springfox-swagger-ui</artifactId>
    			<version>2.4.0</version>
    		</dependency>
    	</dependencies>

###### 创建swagger配置类 ######

package com.xqm.config;
    
    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.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration // spring boot配置注解
    @EnableSwagger2 // 启用swagger2功能注解
    public class Swagger2Config { 
    	@Bean
    	public Docket createRestfulApi() { // api文档实例
    		return new Docket(DocumentationType.SWAGGER_2)// 文档类型：DocumentationType.SWAGGER_2
    				.apiInfo(apiInfo())// api信息
    				.select()// 构建api选择器
    				.apis(RequestHandlerSelectors.basePackage("com.xqm.controller"))// api选择器选择api的包(提供接口的包)
    				.paths(PathSelectors.any())// api选择器选择包路径下任何api显示在文档中
    				.build();// 创建文档
    	}
    
    	// 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    	private ApiInfo apiInfo() { 
    		return new ApiInfoBuilder()
    				// 页面标题
    				.title("测试swagger")
    				// 创建人
    				.contact(new Contact("MarryFeng", "http://localhost:8080", ""))
    				// 版本号
    				.version("1.0")
    				// 描述
    				.description("API 描述").build();
    	}
    
    	/* * private ApiInfo apiInfo() {//接口的相关信息 return new ApiInfoBuilder() * .title("Spring Boot中使用Swagger2构建RESTful接口") .description("接口描述") * .termsOfServiceUrl("termsOfServiceUrl") .contact("new Contact") * .version("1.0") * .license("http://springfox.github.io/springfox/docs/current/") * .licenseUrl("http://springfox.github.io/springfox/docs/current/") .build(); } */
    }

###### 创建springboot启动类 ######

package com;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    public class App { 
    
    	public static void main(String[] args) throws Exception { 
    		SpringApplication.run(App.class, args);
    	}
    
    }

###### 启动工程，浏览器输入http://localhost:8080/swagger-ui.html ######

*  看到以下界面就说明构建成功了  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 1]

#### 整合Mybatis提供一个接口供于测试 ####

###### 引入mybatis依赖 ######

<dependency>
    			<groupId>org.mybatis.spring.boot</groupId>
    			<artifactId>mybatis-spring-boot-starter</artifactId>
    			<version>1.1.1</version>
    		</dependency>
    		
    		<dependency>
    			<groupId>mysql</groupId>
    			<artifactId>mysql-connector-java</artifactId>
    		</dependency>

###### 数据库SQL ######

CREATE TABLE `user` (
      `id` int(6) NOT NULL AUTO_INCREMENT,
      `name` varchar(255) COLLATE utf8_unicode_520_ci DEFAULT NULL,
      `age` int(6) DEFAULT NULL,
      PRIMARY KEY (`id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_520_ci

###### 配置YML文件 ######

server:
      port: 8080
    spring:
    
      datasource:
        driver-class-name: com.mysql.jdbc.Driver
        url: jdbc:mysql://localhost:3306/user?useUnicode=true&characterEncoding=utf8
        username: root
        password: root
     
    logging:
      level:
        mapper: debug

###### pojo类 ######

package com.xqm.pojo;
    
    public class User { 
    
    	private Integer id;
    	private String name;
    	private Integer age;
    	
    	public Integer getId() { 
    		return id;
    	}
    	public void setId(Integer id) { 
    		this.id = id;
    	}
    	public String getName() { 
    		return name;
    	}
    	public void setName(String name) { 
    		this.name = name;
    	}
    	public Integer getAge() { 
    		return age;
    	}
    	public void setAge(Integer age) { 
    		this.age = age;
    	}
    	
    	
    	
    }

###### mapper层 ######

package com.xqm.mapper;
    
    import org.apache.ibatis.annotations.Select;
    
    import com.xqm.pojo.User;
    
    public interface UserMapper { 
    
    	@Select("select * from user where id = #{id}")
    	public User getById(Integer id);
    	
    }

###### service层 ######

package com.xqm.service;
    
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.stereotype.Service;
    
    import com.xqm.mapper.UserMapper;
    import com.xqm.pojo.User;
    
    @Service
    public class UserService { 
    
    	@Autowired
    	private UserMapper userMapper;
    
    	public User getById(Integer id) { 
    		return userMapper.getById(id);
    	}
    }

###### controller层（根据Id查询User信息） ######

package com.xqm.controller;
    
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.xqm.pojo.User;
    import com.xqm.service.UserService;
    
    @RestController
    public class UserController { 
    
    	@Autowired
    	private UserService userService;
    
    	@RequestMapping("getById")
    	public User getById(Integer id) { 
    		return userService.getById(id);
    	}
    }

###### 启动类加上扫mapper包的注解 ######

package com;
    
    import org.mybatis.spring.annotation.MapperScan;
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    
    @SpringBootApplication
    @MapperScan("com.xqm.mapper")//扫描mapper包
    public class App { 
    
    	public static void main(String[] args) throws Exception { 
    		SpringApplication.run(App.class, args);
    	}
    
    }

###### 启动项目地址栏输入[http://localhost:8080/getById?id=1][http_localhost_8080_getById_id_1] ######

![在这里插入图片描述][20191014003130981.png]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 2]

*  看到查询出数据说明接口写的没有问题

###### 运行[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]看有没有接口生产 ######

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 3]

*  很显然没有看到接口生产

###### 改造controller层 ######

package com.xqm.controller;
    
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    import com.xqm.pojo.User;
    import com.xqm.service.UserService;
    
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    
    @RestController
    @Api(value = "用户接口", tags = {  "userAPi" }) 
    public class UserController { 
    
    	@Autowired
    	private UserService userService;
    
    	@RequestMapping("getById/{id}")
    	@ApiOperation(value = "根据userId查询用户信息", notes = "查询数据库中用户信息")
    	@ApiImplicitParam(name="id",value="userId",paramType = "path",required=true,dataType = "Integer")
    	public User getById(@PathVariable Integer id) { 
    		return userService.getById(id);
    	}
    }

###### 再次输入[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html] ######

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 4]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 5]

*  点开后发现有多个请求，但请求方式不同，那是因为我们接口上使用的是@RequestMapping这个注解，一般在实际开发中我们都要指定请求方式，我们把它改成@GetMapping再看

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 6]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 7]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 8]

###### 最终工程结构展示 ######

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 9]

###### swagger的一些注解及参数说明 ######

> @Api：用在请求的类上，表示对类的说明  
> tags=“说明该类的作用，可以在UI界面上看到的注解”  
> value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”  
> @ApiOperation：用在请求的方法上，说明方法的用途、作用  
> value=“说明方法的用途、作用”  
> notes=“方法的备注说明”  
> @ApiImplicitParams：用在请求的方法上，表示一组参数说明  
> @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面  
> name：参数名  
> value：参数的汉字说明、解释  
> required：参数是否必须传  
> paramType：参数放在哪个地方  
> header --> 请求参数的获取：@RequestHeader  
> query --> 请求参数的获取：@RequestParam  
> path（用于restful接口）–> 请求参数的获取：@PathVariable  
> body（不常用）  
> form（不常用）  
> dataType：参数类型，默认String，其它值dataType=“Integer”  
> defaultValue：参数的默认值  
> @ApiResponses：用在请求的方法上，表示一组响应  
> @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息  
> code：数字，例如400  
> message：信息，例如"请求参数没填好"  
> response：抛出异常的类  
> @ApiModel：用于响应类上，表示一个返回响应数据的信息  
> (这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）  
> @ApiModelProperty：用在属性上，描述响应类的属性

下期再见。。。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70]: /images/20230601/8b728884a92c4adb993c31fa1f1fa557.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 1]: /images/20230601/a57379a0e3b74bd8a3e3feacdb4f6a57.png
[http_localhost_8080_getById_id_1]: http://localhost:8080/getById?id=1
[20191014003130981.png]: /images/20230601/8023826fae4944d6a2ea982872cd3b7b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 2]: /images/20230601/fb7fed650a834c848148a74cbdd7a160.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 3]: /images/20230601/66dfc381564746feaa55f5b85ad3d4e6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 4]: /images/20230601/7b49dfe81a45408b90b50dc5aa828626.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 5]: /images/20230601/597f088fad1a454ca392b6d9e72065a4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 6]: /images/20230601/2ceceb5a6f3f4f9a88bbb3bbdb0bfc7e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 7]: /images/20230601/a94b09a02a6745c6906b6ef0332d870e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 8]: /images/20230601/fb2fca6d5b80458fab262f17a0516cc1.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80Mjg0MTQzMw_size_16_color_FFFFFF_t_70 9]: /images/20230601/14f82b0288e4450699c10469eb37a52d.png