swagger快速入门
- 什么是swagger
- 什么是springfox
- 什么是swagger-bootstrap-ui
- 使用方法
- 第一步
- 第二步
- 第三步
- 完整代码
- 特别注意
什么是swagger
swagger是个辅助工具，帮你设计接口API，实现接口API的文档，甚至可以对接口API进行测试。
什么是springfox
这就是对swagger规范在spring下的实现。对我们看得到的界面就是springfox-swagger-ui
什么是swagger-bootstrap-ui
国人开发的对springfox的增加，之所以用他，就是其动态注释的功能不错，而且兼容了原springfox所有功能。
官网地址
/springfox/
/
/guide/
使用方法
第一步
制作封面文档，或者说配置项
package com.example.demospringboot.config;
import com.fasterxml.classmate.TypeResolver;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.beans.factory.annotation.Autowired;
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.service.Tag;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class Swagger2Config {
@Autowired
private TypeResolver resolver;
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("雇员文档")
.select()
.apis(RequestHandlerSelectors
.basePackage(""))
.paths(PathSelectors.regex("/.*"))
.build().apiInfo(apiEndPointsInfo())
.tags(new Tag("雇员服务", "所有有关雇员的接口"))
;
}
@Bean
public Docket api2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("部门文档")
.select()
.apis(RequestHandlerSelectors
.basePackage(""))
.paths(PathSelectors.regex("/.*"))
.build().apiInfo(apiEndPointsInfo())
.tags(new Tag("部门服务", "所有有关部门的接口"));
}
// @Bean
// public Docket api3() {
// return new Docket(DocumentationType.SWAGGER_2)
// .select()
// .apis(RequestHandlerSelectors
// .basePackage(""))
// .paths(("/.*"))
// .build().apiInfo(apiEndPointsInfo())
// .tags(new Tag("所有服务", "所有的接口"));
// }
private ApiInfo apiEndPointsInfo() {
return new ApiInfoBuilder().title("MarsZhang 接口文档")
.description("实际样例 REST API")
.contact(new Contact("Mars Zhang", "/makefriend7", "6671605@"))
.license("mars 0.1")
.licenseUrl("/makefriend7")
.version("0.1")
.build();
}
}
第二步
当然就是自定义的注解了。
package com.example.demospringboot.controller.depcontroller;
import com.example.demospringboot.domains.Department;
import com.example.demospringboot.domains.Employee;
import com.example.demospringboot.mapper.DepartmentMapper;
import com.example.demospringboot.mapper.EmployeeMapper;
import com.google.gson.JsonObject;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RestController
@RequestMapping("/department")
public class DepartmentController {
private static Logger logger = LoggerFactory.getLogger(DepartmentController.class);
@Autowired
DepartmentMapper deptMapper;
@Autowired
EmployeeMapper empMapper;
@GetMapping("/dept/{deptCode}")
public Department getDepartmentByCode(@PathVariable String deptCode){
Department dept = deptMapper.getDepartmentByDeptCode(deptCode);
return dept;
}
@GetMapping("/{deptCode}")
public List<Employee> getEmployeeByDeptCode(@PathVariable String deptCode){
return empMapper.getEmployeeByDeptCode(deptCode);
}
@ApiOperationSupport(params = @DynamicParameters(name = "ClassNameUUID81aecb92a276",properties = {
@DynamicParameter(name = "deps",value = "在哪些部门",example = "第一部门",required = true),
@DynamicParameter(name = "type",value = "哪种类型",example = "3",required = true,dataTypeClass = Integer.class)
})
,responses = @DynamicResponseParameters(properties = {
@DynamicParameter(value = "返回状态",name = "result", example = "0", required = true, dataTypeClass = Integer.class),
@DynamicParameter(value = "描述",name = "desc"),
@DynamicParameter(value = "结果形式",name = "para",dataTypeClass = Employee.class )
})
)
@ApiOperation(value = "自定义参数查询部门相关信息1")
@RequestMapping(value="/cusSearchDep",method = RequestMethod.POST, produces = "application/json;charset=UTF-8")
public JsonObject cutSearchDep(
@RequestBody JsonObject jsonObject){
//("begin custom search " + ());
JsonObject jsonObject2 = new JsonObject();
jsonObject2.addProperty("result",0);
jsonObject2.addProperty("desc","成功");
jsonObject2.addProperty("para","暂时为空");
String strTmp = jsonObject2.toString();
logger.info("stTmp is " + strTmp);
return jsonObject2;
}
@ApiOperationSupport(params = @DynamicParameters(name = "ClassNameUUID1191aecb92a276",properties = {
@DynamicParameter(name = "deps",value = "在哪些部门",example = "第二部门",required = true),
@DynamicParameter(name = "type",value = "哪种类型",example = "2",required = true,dataTypeClass = Integer.class)
})
)
@ApiOperation(value = "自定义参数查询部门相关信息2")
@RequestMapping(value="/cusSearchDep2",method = RequestMethod.POST, produces = "application/json;charset=UTF-8")
public String cutSearchDep2(
@RequestBody String strTmp2){
logger.info("begin custom search 2 " + strTmp2);
JsonObject jsonObject3 = new JsonObject();
String strTmp = "aaaa";
logger.info("stTmp is " + strTmp);
return strTmp;
}
@ApiOperationSupport(params = @DynamicParameters(name = "ClassNameUUID2293aecb92a276",properties = {
@DynamicParameter(name = "deps",value = "在哪些部门",example = "第三部门",required = true),
@DynamicParameter(name = "type",value = "哪种类型",example = "3",required = true,dataTypeClass = Integer.class)
})
)
@ApiOperation(value = "自定义参数查询部门相关信息3")
@RequestMapping(value="/cusSearchDep3",method = RequestMethod.POST, produces = "application/json;charset=UTF-8")
public String cutSearchDep3(
@RequestBody JsonObject jsonObject){
logger.info("begin custom search 3 " + jsonObject.toString());
String strTmp = "aaaa";
logger.info("stTmp is " + strTmp);
return strTmp;
}
}
第三步
访问 http://127.0.0.1:8080/#
完整代码
/makefriend8/spring-sample/tree/master/spring-boot-swagger
特别注意
文档中使用的类库 implementation ‘:swagger-bootstrap-ui:1.9.5’
实际下载地址为/makefriend8/swagger-bootstrap-ui/attach_files/262839/download
请手工安装