html|swagger2 使用教程 spring|boot|java|swagger2

swagger2是一款用于前后端分离的api文档生成工具，话不多说直接上教程。
1.第一步就是导入依赖；版本问题大家不要在意，会教大家一个忽略版本变化的方式。

io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2

2.编写一个helloController

@RestController public class HelloController { @RequestMapping("/hello") public String Hello() { return "hello"; } }

3.编写配置类，重点来了，忽略版本的方式就是看源码。其实里边啥也不用配就可以访问http://localhost:8080/swagger-ui.html 来查看了。简单测试一下发现可以访问继续配置。

@Configuration//标记这是一个配置类 @EnableSwagger2 //开启swagger2 public class Swagger2 {}

我们点进去docket发现这些东西，再看一下ApiInfo里都写了什么，点进去就是Ctrl加鼠标左键

文章图片
这就是默认的ApiInfo配置，那么这个DEFAULT_CONTACT,是啥呢，我们看这个类的最上边，

文章图片
发现这个DEFAULT_CONTACT是这样配置的

文章图片

配置扫描包，可以看到有这些配置，paths下边的就是一个过滤的根据情况自己配置即可，一般配置any（）；.enable()就是是否启动一般为true就可以，默认值为true，无需配置，这个一般用在生产环境和发布环境，在配置文件中配置值，然后引用

文章图片

//basePackage() 指定要扫描的包 //any() 扫描全部 //none() 不扫描 //withClassAnnotation() 扫描类上的注解，参数是一个注解的反射对象 (Controller.class) //withMethodAnnotation() 扫描方法上的注解（GetMapping.class）

下边我编辑一个完整配置

@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.gao.controller")) .paths(PathSelectors.any()) //可以根据url路径设置哪些请求加入文档，忽略哪些请求 .build(); } public static final Contact DEFAULT_CONTACT = new Contact("xxx", "https://baid.com/", "xxx@qq.com"); private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文档") //设置文档的标题 .description("如有疑问请联系QQ") //设置文档的描述 .termsOfServiceUrl("www.baidu.com")//这个就是一个团队服务的网站，如果有就写，没有就随便写一个，写个空字符串也行 .contact(DEFAULT_CONTACT) //作者信息 .version("1.0") //版本 .build(); } }

完整测试一下：可以看到现在下边的实体类不见了，只要我们的接口中返回值存在实体类就会在swagger2中出现

文章图片

简单编写一个方法在HelloController中，测试，models出现，
@ApiModel("用户实体类")对实体类注解就在文档中出现，
@ApiModelProperty("昵称")这个注解是对字段用的，
【html|swagger2 使用教程】@ApiOperation("hello方法")：描述一个类的一个方法，是在controller类中定义的方法上使用
@ApiParam("用户名")：描述参数的作用
@ApiError ：发生错误返回的信息