推荐一个软件自动生成接口文档（带实现）

Swagger2

上次给大家推荐Swagger2这个神器，自动生成接口文档。不需要自己再专门写文档，对于程序员来说能提高工作效率。

但是上篇并没有讲怎么使用Wagger2这个软件，今天就带大家实现下。

环境

使用的语言是Java,其他语言也有类型的实现。官网链接:swagger2

框架是SpringBoot,构建工具是gradle.

实现

构建组件

在微服务开发中，我们会创建多个后端程序，在每个程序上都将swagger2的配置写一遍，显得很臃肿，我们这次在开发的时候将swagger2打造成一个组件的方式，后期直接引用。

新建立Gradle项目

// 增加依赖
dependencies {
    compile("io.springfox:springfox-swagger2:2.9.1")
    compile("io.springfox:springfox-swagger-ui:2.9.1")
    compile("org.springframework.boot:spring-boot-autoconfigure:1.5.10.RELEASE")
    compileOnly("org.springframework.data:spring-data-commons:1.12.6.RELEASE")
}

创建依赖的类

// 注意有些参数我们是通过配置文件配置过来的
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Resource
    SwaggerProperties swaggerProperties;

    /** 
     * 注入docket
     * @return: Docket 
     * @author: fruiqi
     * @date: 19-2-18 下午6:20
     */ 
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(createApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePacakge()))
                .paths(PathSelectors.any())
                .build();
    }

    /** 
     * 创建api 
     * @return: springfox.documentation.service.ApiInfo 
     * @author: fruiqi
     * @date: 19-2-18 下午6:20
     */ 
    private ApiInfo createApiInfo(){
        return new ApiInfoBuilder()
                .title(swaggerProperties.getTitle())
                .description(swaggerProperties.getDescription())
                .version(swaggerProperties.getVersion())
                .build();
    }


}

读取配置文件的类

@Configuration
public class SwaggerProperties {

    /**
     * 标题 默认
     */
    @Value("${swagger.title}")
    private String title = "标题";

    /**
     * 描述
     */
    @Value("${swagger.description}")
    private String description = "描述";

    /**
     * 版本号
     */
    @Value("${swagger.version}")
    private String version = "1.0.0";

    /**
     * 包路径信息
     */
    @Value("${swagger.basepackage}")
    private String basePacakge = "com.infervision";

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public String getVersion() {
        return version;
    }

    public void setVersion(String version) {
        this.version = version;
    }

    public String getBasePacakge() {
        return basePacakge;
    }

    public void setBasePacakge(String basePacakge) {
        this.basePacakge = basePacakge;
    }
}

我们的文件属性放到配置文件中，作为组件内容引入到别的项目中，配置文件类中使用的属性从其他项目配置文件获取。

其他项目引入上面的wagger组件，组件的项目名称
compile project(':swagger-manage')

//配置文件如下
swagger:
  title: test
  description: 开发devapi
  version: 1.0.0
  basepackage: com.infervision

我们在其他项目可以随意引入该组件，但更好的引入方式可以将其打成mavenjar包，放到maven仓库中，以后可以使用maven的方式调用自己生成的swagger组件。

使用

创建Controller类，使用不同的注解标识我们创建的接口。

@RestController
@RequestMapping("people")
@Api(value = "people", description = "用户控制端")
public class PeopleController {

    /**
     * 日志
     */
    private static final Logger logger = LoggerFactory.getLogger(PeopleController.class);

    @Autowired
    PeopleService peopleService;


    /**
     * 根据用户实体内容 分类查询用户
     * 1. 在这里 vo层将查询条件封装成为一个实体或者
     * 参数较少可以直接使用RESTful的方式将其传参
     * @param people 用户实体
     * @return: com.infervision.model.People
     * @author: fruiqi
     * @date: 19-2-20 上午10:45
     */
    @GetMapping
    @ApiOperation(value = "获取用户列表信息", notes = "条件可以选择 用户名,公司等内容")
    public List getPeoples(PeopleVo people) throws CommonException {
        List peoples = peopleService.getPeoples(people);
        return peoples;
    }


    /**
     * 增加用户信息
     *
     * @param peopleVo 增加的用户信息
     * @return: com.infervision.model.PeopleVo
     * @author: fruiqi
     * @date: 19-2-20 下午3:31
     */
    @PostMapping
    @ApiOperation(value = "增加用户")
    public PeopleVo addPeople(@RequestBody  PeopleVo peopleVo) {
        PeopleVo result = peopleService.addPeople(peopleVo);
        return result;
    }

    /**
     * 修改对象
     * @param id       用户id
     * @param peopleVo 修改的对象
     * @return: com.infervision.model.PeopleVo
     * @author: fruiqi
     * @date: 19-2-20 下午4:06
     */
    @PutMapping("{id}")
    @ApiOperation(value="更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true)
    })
    public PeopleVo updatePeople(@PathVariable Integer id, @RequestBody PeopleVo peopleVo) {
        PeopleVo result = peopleService.updatePeople(id, peopleVo);
        return result;
    }


    @DeleteMapping("{id}")
    @ApiOperation(value="删除用户")
    @ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true)
    public void deletePeople(@PathVariable Integer id){

        if (id != null){
            peopleService.deletePeople(id);
            logger.info("[INFO]  删除用户id  ");
        }


    }


}

成功示意图

总结

上面的实现方式我们就打造成一个wagger2的组件了，后期我们在使用就可以直接引入项目。

源码地址：https://github.com/menhuan/notes/tree/master/code/codebase-master/swagger-manage

可以直接获取组件内容。

后缀内容

·END·

路虽远，行则必至

本文原发于 同名微信公众号「胖琪的升级之路」，回复「1024」你懂得，给个赞呗。

微信ID：YoungRUIQ