Swagger-API文档生成框架的基本使用

使用工具、框架的目的就是为了开发过程简洁方便或者是达到更强大的功能效果。在目前互联网开发发展的趋势下，由于技术更加深度化、细化，前后端分离开发成为必不可少的一个环节，而后端和前端开发人员之间唯一的桥梁便是API文档，也就是接口文档。
　　平时开发中大部分接口开发都会由开发者或者特定人员手写接口文档。而文档也会随着项目迭代不停更新，由此需要不停有人员维护API文档的内容。消耗时间同时也需要消耗人力资源。由此原因我有了接触和了解一些API文档生成工具的机会。
　　了解到了部分的API工具，首先的话是RAP，这个项目好像是阿里开发的，github地址为：https://github.com/thx/RAP 这里的话最后还是选择了swagger，以下先介绍下swagger这个工具

1.pom.xml配置

<!--Swagger-API文档生成框架-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.7.0</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.6.5</version>
		</dependency>
		<!-- Swagger-API文档配置结束-->

2.建一个swagger的配置类,配置一些当前生成文档的基本信息

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 Config
 *
 * @author hzk
 * 正常这里使用@Configuration初始化配置,如果项目引入junit测试需要使用@WebAppConfiguration
 * 访问项目/v2/api-docs会展现以下格式生成的数据就证明我们的文档注解解析成功
 * http://localhost:8099/demo/v2/api-docs
 */
@Configuration
@EnableSwagger2
@ComponentScan("com.example.demo.controller")
public class SpringfoxConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ithzk.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("HuZeKun", "", "[email protected]");
        return new ApiInfoBuilder()
                .title("Swagger 1.x API接口文档")
                .description("")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}

3.controller层编写@api

package com.example.demo.controller;


import com.example.demo.entity.Tuser;
import com.example.demo.service.ITuserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
//import com.baomidou.ant.common.BaseController;

import java.util.List;

/**
 * <p>
 * 用户 前端控制器
 * </p>
 *
 * @author jobob
 * @since 2019-01-08
 */
@RestController
@RequestMapping("/demo/tuser")
@Api(value="测试Controlle接口",tags = "接口信息",description = "相关接口")
public class TuserController /*extends BaseController*/ {
    @Autowired
    ITuserService service;

    @RequestMapping("")
    @ResponseBody
    @ApiOperation(value = "获取测试信息", httpMethod = "GET",response = String.class)
    public String test(){
        List<Tuser> list = service.list(null);
        System.out.println(list.size());
        return "123";
    }

}

4.访问：

访问项目/v2/api-docs会展现以下格式生成的数据就证明我们的文档注解解析成功