Swagger应用例子及说明

编程语言 2018-05-11 23:00:00 阅读次数: 1
Swagger应用例子及说明 


<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"可以，但加了８小时
	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/

猜你喜欢

转载自huangyongxing310.iteye.com/blog/2338224
今日推荐
基于大语言模型的开源知识库问答系统 MaxKB GitHub Star 数量突破 5,000 个！
美国拟限制 AI 大模型出口中国和俄罗斯
苹果将与 OpenAI 达成协议，将 ChatGPT 应用于 iPhone
openKylin 社区生态委员会第六次会议圆满召开
阿里云正式发布通义千问 2.5
Python 3.13 发布首个 Beta：实验性自由线程模式和 JIT、改进交互式解释器
Stack Overflow 拿我的代码去训练 AI 大模型，还封了我的账号
Pop!_OS 的 COSMIC 桌面完成 App Store 上架工作
《2024 年一季度互联网投融资运行情况》研究报告
报告：Django 仍然是 74% 开发者的首选
15 年前上了“FFmpeg 耻辱柱”，今天他还得谢谢咱——腾讯QQPlayer一雪前耻？
TIOBE 5 月榜单：Fortran “复活”进入 Top 10
周排行
记一下去大梅沙的准备（2018-05-26）
Spring 注解 事务
基于HTTP协议的客户端缓存
阿里云rds 备份和还原
[PHP] 几个拖慢 PHP 程序/API 运行速度的点
python 代码风格------------PEP8规则
js控制json生成菜单——自制菜单（一）
将字符串: 'k:1|k1:2|k2:3|k3:4 ' ,处理成 python 字典: {'k':1, 'k1':2, ...}
微信小程序转支付宝小程序
Qt551.窗口滚动条
每日归档
更多
2024-05-13(18)
2024-05-12(0)
2024-05-11(38)
2024-05-10(38)
2024-05-09(35)
2024-05-08(42)
2024-05-07(14)
2024-05-06(40)
2024-05-05(0)
2024-05-04(7)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022