1.引入swagger依赖
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
2.添加swagger配置类
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.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() //swagger文档扫描的包，这里扫描的是全部 //如果扫描指定包下的可以这样写 //.apis(RequestHandlerSelectors.basePackage("com.xxx.yyy.controller")) .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("标题") .description("描述") .version("版本") .termsOfServiceUrl("公司网址") .build(); } }
3.测试Controller
@RestController @RequestMapping("/test") public class TestController { @GetMapping("/test01") public String test01(){ return "test01"; } @GetMapping("/test02") public String test02(){ return "test02"; } @GetMapping("/test03") public String test03(){ return "test03"; } }
4.测试
项目正常启动后浏览器输入网址
http://localhost:8100/swagger-ui.html#/
（这里的端口填写自己服务的端口，我的是8100，默认端口8080）
测试结果
5.swagger的注解
上面就是swagger的基本使用
但swagger也提供了一些注解，这里例举一些常用注解
Api注解
用于标记当前类为Swagger的文档资源。其中含有几个常用属性，分别说明如下。
• value：定义当前接口文档的名称。
• description：用于定义当前接口文档的介绍。
@Api(value = "controller接口",description = "用户测试接口") public class TestController {
ApiOperation注解
@ApiOperation用在接口的方法上，主要用来注解请求接口。其中包含几个常用属性，分别说明如下。
• value：对API的简短描述。
• note：API的有关细节描述。
• hidden：如果值为true，就会在文档中隐藏。
演示
@GetMapping("/test01") @ApiOperation(value = "测试方法01",notes = "细节的描述，细节的测试",hidden = false) public String test01(){ return "test01"; }
ApiImplicitParam、ApiImplicitParams注解
使用在API请求方法上，@ApiImplicitParams的子集是@ApiImplicitParam注解，其中@ApiImplicitParam注解常用参数。
• name：参数的名称。
• value：参数值。
• required：如果值为true，就是必传字段。
• defaultValue：参数的默认值。
• dataType：数据的类型。
演示
@GetMapping("/test02") @ApiImplicitParams(value = { @ApiImplicitParam(name = "name",value = "测试姓名",required = false,defaultValue = "默认姓名李四"), @ApiImplicitParam(name = "age",value = "测试年龄",required = false,dataType = "Integer",defaultValue = "200") }) public String test02(String name,Integer age){ return "test02 姓名："+name+" 年龄:"+age; }
ApiParam注解
ApiParam用于方法的参数，其中包含以下几个常用属性。
• name：参数的名称。
• value：参数值。
• required：如果值为true，就是必传字段。
• defaultValue：参数的默认值。
• type：参数的类型。
• hidden：如果值为true，就隐藏这个参数。
与ApiImplicitParam、ApiImplicitParams注解类似，不再赘述。
ApiResponse、ApiResponses注解
@ApiResponses和@ApiResponse二者配合使用返回HTTP状态码。@ApiResponses的value值是@ApiResponse的集合，多个@ApiResponse用逗号分隔。其中，@ApiResponse常用参数如下。
• code：HTTP状态码。
• message：HTTP状态信息。
• responseHeaders：HTTP响应头。
演示
@GetMapping("/test03") @ApiResponses(value = { @ApiResponse(code = 200,message = "成功"), @ApiResponse(code = 404,message = "异常") }) public String test03(){ return "test03"; }
ResponseHeader注解
如果需要设置响应头，就将@ResponseHeader设置到@ApiResponse的responseHeaders参数中。@ResponseHeader提供了以下几个参数。
• name：响应头名称。
• description：响应头描述。
ApiModel、ApiModelProperty注解
设置API响应的实体类，用作API返回对象。@ApiModel常用参数。
• value：实体类名称。
• description：实体类描述。
设置API响应实体的属性，其中常用参数。
• name：属性名称。
• value：属性值。
演示
@ApiModel(value = "Student(学生类)",description = "记录学生个人信息") public class Student { public String name; @ApiModelProperty(name = "age",value = "年龄") public Integer age; }
6.更多
本文总结粗略
更多详细使用参照swagger官网
