swagger快速入门(springfox)

什么是swagger

swagger是个辅助工具，帮你设计接口API，实现接口API的文档，甚至可以对接口API进行测试。

什么是springfox

这就是对swagger规范在spring下的实现。对我们看得到的界面就是springfox-swagger-ui

什么是swagger-bootstrap-ui

国人开发的对springfox的增加，之所以用他，就是其动态注释的功能不错，而且兼容了原springfox所有功能。

官网地址
http://springfox.github.io/springfox/
https://swagger.io/
https://doc.xiaominfo.com/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("com.example.demospringboot.controller.employcontroller"))
                .paths(PathSelectors.regex("/.*"))
                .build().apiInfo(apiEndPointsInfo())
                .tags(new Tag("雇员服务", "所有有关雇员的接口"))
                ;
    }

    @Bean
    public Docket api2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("部门文档")
                .select()
                .apis(RequestHandlerSelectors
                        .basePackage("com.example.demospringboot.controller.depcontroller"))
                .paths(PathSelectors.regex("/.*"))
                .build().apiInfo(apiEndPointsInfo())
                .tags(new Tag("部门服务", "所有有关部门的接口"));
    }

//    @Bean
//    public Docket api3() {
//        return new Docket(DocumentationType.SWAGGER_2)
//                .select()
//                .apis(RequestHandlerSelectors
//                        .basePackage("com.example.demospringboot.controller"))
//                .paths(PathSelectors.regex("/.*"))
//                .build().apiInfo(apiEndPointsInfo())
//                .tags(new Tag("所有服务", "所有的接口"));
//    }


    private ApiInfo apiEndPointsInfo() {

        return new ApiInfoBuilder().title("MarsZhang  接口文档")
                .description("实际样例 REST API")
                .contact(new Contact("Mars Zhang", "blog.csdn.net/makefriend7", "6671605@qq.com"))
                .license("mars 0.1")
                .licenseUrl("blog.csdn.net/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){
        //logger.info("begin custom search " + jsonObject.toString());
        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/swagger-ui.html#

完整代码

https://gitee.com/makefriend8/spring-sample/tree/master/spring-boot-swagger

特别注意

文档中使用的类库 implementation ‘com.github.xiaoymin:swagger-bootstrap-ui:1.9.5’
实际下载地址为https://gitee.com/makefriend8/swagger-bootstrap-ui/attach_files/262839/download
请手工安装