<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency>
package com.cesmart; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.EnableAutoConfiguration; import org.springframework.context.ApplicationContext; import org.springframework.context.annotation.ComponentScan; @EnableAutoConfiguration @ComponentScan(basePackages = "com.cesmart") // 扫描那些包得到bean.@ComponentScan({"com.teradata.notification","com.teradata.dal"}) //@EnableSwagger2 //启动swagger注解 public class Application { public static void main(String[] args) { ApplicationContext applicationContext = SpringApplication.run(Application.class, args); } }
package com.cesmart.entity; public class TestModel { private String name; // private String value; // public String getName() { return name; } public void setName(String name) { this.name = name; } public String getValue() { return value; } public void setValue(String value) { this.value = value; } @Override public String toString() { return "TestModel [name=" + name + ", value=" + value + "]"; } }
package com.cesmart.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import com.google.common.base.Predicates; 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//定义为spring boot 的配置文件 @EnableSwagger2//启动swagger注解 public class Swagger2 { public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.cesmart.controller"; @Bean(value="createRestApi") public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("test1") .pathMapping("/") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)) .paths(Predicates.or(PathSelectors.regex("/webTest2/.*"))) .build(); //groupName,分组名字 //pathMapping,映射路径(会加到URL前面组成新的路径,如:"/xing/WebTest/webTest",(pathMapping("/xing"))) //apiInfo,API信息描述 //select, 选择那些路径和api会生成document //apis,扫描那些包,RequestHandlerSelectors.any()表示对所有api进行监控 //paths,匹配那些路径,PathSelectors.any()表示所有路径, } @Bean(value="createRestApi2") public Docket createRestApi2() { return new Docket(DocumentationType.SWAGGER_2) .groupName("test2") .pathMapping("/") .apiInfo(apiInfo2()) .select() .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)) .paths(Predicates.or(PathSelectors.regex("/webTest/.*"))) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("更多Spring Boot相关文章请关注:http://blog.didispace.com/") .termsOfServiceUrl("http://blog.didispace2.com/") .contact("程序猿DD") .version("1.0") .license("license") .licenseUrl("licenseUrl") .build(); //title,标题,在页面顶部显示 //description,描述,在页面顶部显示 //termsOfServiceUrl, //contact,显示“Created by + contact”,在页面顶部显示 //version,API版本,,在页面顶部显示 //license,版权 } private ApiInfo apiInfo2() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("更多Spring Boot相关文章请关注:http://blog.didispace.com/") .termsOfServiceUrl("http://blog.didispace2.com/") .contact("程序猿DD") .version("1.0") .license("license") .licenseUrl("licenseUrl") .build(); } }
package com.cesmart.controller; import org.springframework.web.bind.annotation.ModelAttribute; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import com.cesmart.entity.TestModel; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; @RestController @Api(value = "WebTest", description = "有关于Swagger2操作") @RequestMapping(value = "/webTest") // 用在类上,说明该类的作用 // value,显示在类中的说明 // description,类中的说明 // 显示形式:“value:description”,如上面显示为"WebTest:有关于Swagger2操作" public class WebTest { @ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) // 用在方法上,说明方法的作用 // 显示在方法说明中,显示notes // response,接口返回参数类型 // value = "接口说明", // notes = "接口发布说明" @ApiImplicitParams({ @ApiImplicitParam(paramType = "path", required = true, name = "test", dataType = "String", value = "456"), @ApiImplicitParam(paramType = "path", required = true, name = "test2", dataType = "String", value = "789") }) // @ApiImplicitParam,表示一个参数的描述,与请求参数有关系 // paramType,参数放在哪个地方 // required,参数是否必须传 // name,参数名 // dataType,参数类型(描述) // value,参数的意思(描述) @ApiParam @RequestMapping(value = "/webTest/{test}/{test2}", produces = "text/plain;charset=UTF-8", method = RequestMethod.GET) public String webTest(@PathVariable("test") String test, @PathVariable("test2") String test2) { System.out.println("webTest"); System.out.println("test == " + test); System.out.println("test2 == " + test2); return "webTest"; } @ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", required = true, name = "test", dataType = "String", value = "456"), @ApiImplicitParam(paramType = "query", required = true, name = "test2", dataType = "String", value = "789") }) @RequestMapping(value = "/webTest2", produces = "text/plain;charset=UTF-8", method = RequestMethod.POST) public String webTest2(String test, String test2) { System.out.println("webTest"); System.out.println("test == " + test); System.out.println("test2 == " + test2); return "webTest"; } @ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", required = true, name = "name", dataType = "String", value = "456"), @ApiImplicitParam(paramType = "query", required = true, name = "value", dataType = "String", value = "789") }) @RequestMapping(value = "/webTest3", produces = "text/plain;charset=UTF-8", method = RequestMethod.POST) public String webTest3(@ModelAttribute TestModel testModel) { // 这里要用@ModelAttribute,才不会出现testModel输入框 System.out.println("testModel == " + testModel.toString()); return "webTest"; } }
package com.cesmart.controller; import org.springframework.web.bind.annotation.ModelAttribute; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; import com.cesmart.entity.TestModel; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; @RestController @Api(value = "WebTest", description = "有关于Swagger2操作",,tags="设备在线时长统计接口") @RequestMapping(value = "/webTest2") // 用在类上,说明该类的作用 // value,显示在类中的说明 // description,类中的说明 // 显示形式:“value:description”,如上面显示为"WebTest:有关于Swagger2操作" public class WebTest2 { @ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) // 用在方法上,说明方法的作用 // 显示在方法说明中,显示notes // response,接口返回参数类型 // value = "接口说明", // notes = "接口发布说明" @ApiImplicitParams({ @ApiImplicitParam(paramType = "path", required = true, name = "test", dataType = "String", value = "456"), @ApiImplicitParam(paramType = "path", required = true, name = "test2", dataType = "String", value = "789") }) // @ApiImplicitParam,表示一个参数的描述,与请求参数有关系 // paramType,参数放在哪个地方 // required,参数是否必须传 // name,参数名 // dataType,参数类型(描述) // value,参数的意思(描述) @ApiParam @RequestMapping(value = "/webTest/{test}/{test2}", produces = "text/plain;charset=UTF-8", method = RequestMethod.GET) public String webTest(@PathVariable("test") String test, @PathVariable("test2") String test2) { System.out.println("webTest"); System.out.println("test == " + test); System.out.println("test2 == " + test2); return "webTest"; } @ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", required = true, name = "test", dataType = "String", value = "456"), @ApiImplicitParam(paramType = "query", required = true, name = "test2", dataType = "String", value = "789") }) @RequestMapping(value = "/webTest2", produces = "text/plain;charset=UTF-8", method = RequestMethod.POST) public String webTest2(String test, String test2) { System.out.println("webTest"); System.out.println("test == " + test); System.out.println("test2 == " + test2); return "webTest"; } @ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) @ApiImplicitParams({ @ApiImplicitParam(paramType = "query", required = true, name = "name", dataType = "String", value = "456"), @ApiImplicitParam(paramType = "query", required = true, name = "value", dataType = "String", value = "789") }) @RequestMapping(value = "/webTest3", produces = "text/plain;charset=UTF-8", method = RequestMethod.POST) public String webTest3(@ModelAttribute TestModel testModel) { // 这里要用@ModelAttribute,才不会出现testModel输入框 System.out.println("testModel == " + testModel.toString()); return "webTest"; } }
说明: @Api:用在类上,说明该类的作用 @ApiOperation:用在方法上,说明方法的作用 @ApiImplicitParams:用在方法上包含一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 paramType:参数放在哪个地方 header-->请求参数的获取:@RequestHeader query-->请求参数的获取:@RequestParam path(用于restful接口)-->请求参数的获取:@PathVariable body(不常用) form(不常用) name:参数名 dataType:参数类型 required:参数是否必须传 value:参数的意思 defaultValue:参数的默认值 @ApiResponses:用于表示一组响应 @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类 @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候) @ApiModelProperty:描述一个model的属性
本地打开: http://localhost:8080/swagger-ui.html
日期使用格式输入注解
public String getDeviceOnlineTimeByYearMonth2(String deviceType, String modelNo, String deviceId, int groupType, @DateTimeFormat(pattern = "yyyyMMdd") Date startDate, @DateTimeFormat(pattern = "yyyyMMdd") Date endDate) {
也可以在接口处使用模型的方式进行,相关参数设定放在模型中进行设置
public class ParamModel { private Long id; private String nameId; @ApiModelProperty(required = true, dataType = "int", value = "1235", name = "xing") private Integer age; @ApiModelProperty(required = true, dataType = "date", value = "时间(yyyyMMdd)") @ApiParam(defaultValue = "20170213") @DateTimeFormat(pattern = "yyyyMMdd") private Date time; }
不在接口处写@ApiImplicitParams也是会识别出来的,只不过让你对参数进行更多的处理
增加公共参数
class SwaggerConfiguration { @Bean public Docket createRestApi() { ParameterBuilder builder = new ParameterBuilder(); Parameter parameter = builder .parameterType("query") //参数类型支持header, cookie, body, query etc .name("access_token") //参数名 .description("请输入您的Access Token") .modelRef(new ModelRef("string"))//指定参数值的类型 .required(false) .build(); List<Parameter> parameters = Lists.newArrayList(parameter); return new Docket(DocumentationType.SWAGGER_2) .groupName("zlcloud-mkt-mfc-service") .pathMapping("/") .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.zlcloud.mfc.controller")) .paths(PathSelectors.any()) .build() .globalOperationParameters(parameters); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("[RESTful APIs]--zlcloud-mkt-mfc-service") .description("zlcloud-mkt-mfc-service模块接口") .contact("ZL") .version("1.0") .build(); } }
使用模型进行参数传递
public AjaxResult findByStatus(@RequestBody SalesParameterModel salesParameterModel) @ApiModel @Table(name = "t_sell_goods") public class Goods implements Serializable { private static final long serialVersionUID = -8444776915480123879L; /** * 唯一码 */ @Id @ApiModelProperty(required = false, name = "goodsid", value = "唯一码",example="123456",position=1) private Long goodsid; }
@ApiOperation(value = "接口说明", notes = "接口发布说明", response = String.class) @RequestMapping(value = "/test4", produces = "text/plain;charset=UTF-8", method = RequestMethod.POST) public String webTest4(@ApiParam(value="地址",defaultValue="123456") @RequestParam(required = true) String address) { System.out.println("dateTimeFormatTestModel == " + address.toString()); return "test3"; }
@JsonFormat
public class DateTimeFormatTestModel2 { @ApiModelProperty(required = false, name = "userId", value = "userId", example = "userId") private String userId; @ApiModelProperty(required = false, name = "date", value = "date yyyyMMdd", example = "20170809") @JsonFormat(pattern="yyyyMMdd",timezone="GMT+8") //输入时可以用,输出时也可以用,//为了便于date类型字段的序列化和反序列化 //@DateTimeFormat(pattern = "yyyy-MM-dd") //yyyyMMdd在bean中的用是不能够进行转换的,但"yyyy-MM-dd"可以,但加了8小时 private Date date; @ApiModelProperty(required = false, name = "name", value = "name", example = "name") private String name;
参考原文(使用例子): http://www.iteye.com/topic/1145103
参考原文(使用例子): http://www.open-open.com/lib/view/open1455546851058.html
参考原文(定义多个组): http://blog.csdn.net/catoop/article/details/50668896
参考原文(使用例子): http://www.jianshu.com/p/8033ef83a8ed
参考原文(注解使用说明(英文)): https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
参考原文(注解使用说明,使用例子): http://www.cnblogs.com/java-zhao/p/5348113.html
参考原文(注解使用说明(英文)): https://github.com/swagger-api/swagger-core/wiki/Annotations
参考原文(官网): http://swagger.io/specification/