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

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<PeopleVo> getPeoples(PeopleVo people) throws CommonException {
        List<PeopleVo> 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