好程序员Java培训分享Swagger使用方法：1.swagger介绍

　　现在开发，很多采用前后端分离的模式，前端只负责调用接口，进行渲染，前端和后端的唯一联系，变成了API接口。因此，API文档变得越来越重要。swagger是一个方便我们更好的编写API文档的框架，而且swagger可以模拟http请求调用。

　　大部分采取的方式：Vue + SpringBoot，Vue通过js渲染页面，后端把数据传递给js，早期前端只负责写页面，然后把写好的HTML页面给后端，后端使用模板引擎(Jsp，Thymeleaf、 freemarker)进行开发。

　　前后端分离的好处：各自开发，相对独立，松耦合，前后端通过API进行交互，后端提供接口给前端，前端去调用该接口，但可能会导致前后端团队人员不能做到及时协商，出现一些问题。解决方式：早期使用实时更新文档，但非常繁琐，后来又使用postman来进行一些测试。

　　2.springboot中集成swagger使用步骤：

　　导入依赖

　　io.springfox

　　springfox-swagger-ui

　　2.9.2

　　io.springfox

　　springfox-swagger2

　　2.9.2

　　创建配置类

　　@Configuration

　　@EnableSwagger2//开启Swagger2

　　public class SwaggerConfig {

　　}

　　然后启动测试运行，看到如下页面：

　　手动配置实例，修改SwaggerConfig配置类

　　package com.qf.swagger.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.spi.DocumentationType;

　　import springfox.documentation.spring.web.plugins.Docket;

　　import springfox.documentation.swagger2.annotations.EnableSwagger2;

　　@Configuration

　　@EnableSwagger2//开启Swagger2

　　public class SwaggerConfig {

　　//配置Swagger的Bean实例

　　@Bean

　　public Docket swaggerSpringMvcPlugin() {

　　return new Docket(DocumentationType.SWAGGER_2)

　　.apiInfo(apiInfo());

　　}

　　//配置API的基本信息(会在http://项目实际地址/swagger-ui.html页面显示)

　　private ApiInfo apiInfo() {

　　return new ApiInfoBuilder()

　　.title("测试API文档标题")

　　.description("测试api接口文档描述")

　　.termsOfServiceUrl("http://www.baidu.com")

　　.version("1.0")

　　.build();

　　}

　　}

　　然后再次重启测试运行：

　　创建实体类

　　package com.qf.swagger.entity;

　　import io.swagger.annotations.ApiModel;

　　import io.swagger.annotations.ApiModelProperty;

　　@ApiModel("用户实体类")

　　public class User {

　　@ApiModelProperty("用户名")

　　private String username;

　　@ApiModelProperty("密码")

　　private String password;

　　public String getUsername() {

　　return username;

　　}

　　public void setUsername(String username) {

　　this.username = username;

　　}

　　public String getPassword() {

　　return password;

　　}

　　public void setPassword(String password) {

　　this.password = password;

　　}

　　}

　　创建controller

　　package com.qf.swagger.controller;

　　import com.qf.swagger.entity.User;

　　import io.swagger.annotations.Api;

　　import io.swagger.annotations.ApiOperation;

　　import io.swagger.annotations.ApiParam;

　　import org.springframework.web.bind.annotation.GetMapping;

　　import org.springframework.web.bind.annotation.PostMapping;

　　import org.springframework.web.bind.annotation.RequestMapping;

　　import org.springframework.web.bind.annotation.RestController;

　　@Api(description ="用户管理API")

　　@RestController

　　public class UserController {

　　@ApiOperation("添加用户")

　　@PostMapping("/add")

　　public User add(@ApiParam("用户名") String username,@ApiParam("密码") String password){

　　return new User();

　　}

　　@ApiOperation("修改用户")

　　@PostMapping("/update")

　　public String update(){

　　return "修改";

　　}

　　@ApiOperation("删除用户")

　　@GetMapping("/delete")

　　public Boolean delete(@ApiParam("用户编号") Integer id){

　　return true;

　　}

　　@ApiOperation("查询用户")

　　@RequestMapping("/query")

　　public User query(){

　　User user = new User();

　　user.setUsername("jack");

　　user.setPassword("1234");

　　return user;

　　}

　　}

　　修改SwaggerConfig配置类

　　package com.qf.swagger.config;

　　import org.springframework.context.annotation.Bean;

　　import org.springframework.context.annotation.Configuration;

　　import springfox.documentation.builders.ApiInfoBuilder;

　　import springfox.documentation.builders.RequestHandlerSelectors;

　　import springfox.documentation.service.ApiInfo;

　　import springfox.documentation.spi.DocumentationType;

　　import springfox.documentation.spring.web.plugins.Docket;

　　import springfox.documentation.swagger2.annotations.EnableSwagger2;

　　@Configuration

　　@EnableSwagger2//开启Swagger2

　　public class SwaggerConfig {

　　//配置Swagger的Bean实例

　　@Bean

　　public Docket swaggerSpringMvcPlugin() {

　　return new Docket(DocumentationType.SWAGGER_2)

　　.apiInfo(apiInfo())

　　.groupName("yangl")//分组名称(可以创建多个Docket就有多个组名)

　　.enable(true)//enable表示是否开启Swagger

　　.select()

　　//RequestHandlerSelectors指定扫描的包

　　.apis(RequestHandlerSelectors.basePackage("com.qf.swagger.controller"))

　　.build();

　　}

　　//配置API的基本信息(会在http://项目实际地址/swagger-ui.html页面显示)

　　private ApiInfo apiInfo() {

　　return new ApiInfoBuilder()

　　.title("测试API文档标题")

　　.description("测试api接口文档描述")

　　.termsOfServiceUrl("http://www.baidu.com")

　　.version("1.0")

　　.build();

　　}

　　}

　　swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息

　　@Api：修饰整个类，描述Controller的作用

　　@ApiOperation：描述一个类的一个方法，或者说一个接口

　　@ApiModel：用对象来接收参数 ，修饰类

　　@ApiModelProperty：用对象接收参数时，描述对象的一个字段

　　@ApiResponse：HTTP响应其中1个描述

　　@ApiResponses：HTTP响应整体描述，一般描述错误的响应

　　@ApiIgnore：使用该注解忽略这个API

　　@ApiError ：发生错误返回的信息

　　@ApiParam：单个参数描述

　　@ApiImplicitParam：一个请求参数，用在方法上

　　@ApiImplicitParams：多个请求参数