swager2

最新推荐文章于 2024-06-27 20:12:16 发布

原创最新推荐文章于 2024-06-27 20:12:16 发布 · 260 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#java

中间件专栏收录该内容

1 篇文章

订阅专栏

概述

通过注解，快速生成api文档（类似java的doc）

使用

依赖

<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>

配置类

/**
 * Swagger2配置信息
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket webApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                //只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();

    }

    @Bean
    public Docket adminApiConfig(){

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                //只显示admin路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();

    }

    private ApiInfo webApiInfo(){

        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("goku", "http://goku.com", "2356498584@qq.com"))
                .build();
    }

    private ApiInfo adminApiInfo(){

        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("goku", "http://goku.com", "2356498584@qq.com"))
                .build();
    }

}

swager2可视化访问地址

常用注解

@Api：描述类信息（controller）
- tags：“说明该类的作用”
@ ApiOperation：描述接口、方法
- value=“说明方法的作用”
- notes=“方法的备注说明”

@ApiImplicitParams、@ApiImplicitParam：描述方法参数

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
	@ApiImplicitParam：对单个参数的说明	    
    	name：参数名
    	value：参数的说明、描述
    	required：参数是否必须必填
    	paramType：参数放在哪个地方
        	· query --> 请求参数的获取：@RequestParam
        	· header --> 请求参数的获取：@RequestHeader	      
        	· path（用于restful接口）--> 请求参数的获取：@PathVariable
        	· body（请求体）-->  @RequestBody User user
        	· form（普通表单提交）	   
    	dataType：参数类型，默认String，其它值dataType="Integer"	   
  		defaultValue：参数的默认值
  		
@Api(tags="用户模块")
@Controller
public class UserController {

	@ApiOperation(value="用户登录",notes="随边说点啥")
	@ApiImplicitParams({
		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
	@RequestParam Integer age){
		//...
	    return JsonResult.ok(map);
	}
}

@ApiResponses、@ApiResponse：方法返回值的状态码说明

@ApiResponses：方法返回对象的说明
	@ApiResponse：每个参数的说明
	    code：数字，例如400
	    message：信息，例如"请求参数没填好"
	    response：抛出异常的类

@Model：描述javabean
```
@ApiModel(description = "xxxx")
```
@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义
```
@ApiModelProperty(value = "错误码")
private Integer errCode;
```