码迷,mamicode.com
首页 > 其他好文 > 详细

swagger框架

时间:2018-05-30 10:54:04      阅读:223      评论:0      收藏:0      [点我收藏+]

标签:图片   mes   维度   servlet   log4   conf   res   tab   api   

1.1   介绍

  Swagger是一个简单又强大的能为你的Restful风格的Api生成文档工具。在项目中集成这个工具,根据我们自己的配置信息能够自动为我们生成一个api文档展示页,可以在浏览器中直接访问查看项目中的接口信息,同时也可以测试每个api接口。Swagger生成的api文档是实时更新的,你写的api接口有任何的改动都会在文档中及时的表现出来。

1.2  项目环境

Spring提供了一个与Swagger的集成工具包springfox,让我们的Spring项目能够更好的与Swagger融合。详情可访问springfox托管在Github上的demo内容。地址:http://springfox.github.io/springfox/

 

1.3   Swagger配置步骤

1)  第一步,在项目的公共模块pom.xml文件下,引用相关的外部依赖包。如下:

<!-- Swagger2 api文档生成工具依赖包 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-annotations</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-core</artifactId>
<version>2.8.5</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>log4j-over-slf4j</artifactId>
</dependency>
<!-- end -->

2)  第二步,自定义配置类实现。

 

Swagger会根据这个配置类的具体实现来生成我们相应的api文档。通过@ComponentScan注解可以指定扫描的包下的RESTful API接口。regex("/api/v1/.*") 可以根据不同ContentPath 版本接口进行分类。可创建多个Docket实例。

 

@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages ={"com.coracle.jomoo.rest"})
public class SwaggerConfig {

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
                .groupName("api")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(false)
                .pathMapping("/")
                .select()
                .paths(or(regex("/api/v1/.*")))
                .build()
                .apiInfo(apiInfo());
    }

private ApiInfoapiInfo() {
ApiInfoapiInfo = new ApiInfo("JOMOO INTERFACE API",
"JoMoo Interface‘s REST API, for system administrator",
"1.0",
"NO terms of service",
"luowei@coracle.com",
"The Apache License, Version 2.0",
"http://www.apache.org/licenses/LICENSE-2.0.html"
);
return apiInfo;
    }
}

 

3. 通过访问http://localhost:8080/mxm/swagger-ui.html生成在线接口测试地址。

技术分享图片

 

 

3)  第三步,API接口注解

  a.类注解

 技术分享图片

  b.方法注解

 

@ApiOperation(value = "批文列表查询接口",
notes = "批文列表查询接口",
position = 0)
@ApiResponses(value = {@ApiResponse(code = 100, message = "批文列表查询接口异常"),
@ApiResponse(code = 200, message = "批文列表查询接口成功")})
@ResponseBody
@RequestMapping(value = "/list", method = RequestMethod.POST)
public CommonDTO<List<TDocLandInfos>> approvalList(@RequestBody TDocLandInfosParam tDocLandInfosParam, HttpServletRequest request, HttpServletResponse response) throws Exception{
Page page = new Page(request,response);
try {
return listDTO;
}catch (Exception e){
}
return listDTO;
}}

springfox默认会将所有的接口都给你生成文档,不管你有没有使用注解@ApiOperation这个注解注释接口方法,并且如果你没有为你的接口指定访问方式,他也会为这个接口生成所有访问方式的文档, 下面会有结构展示图.

技术分享图片

 

  c.参数注解

 

@ApiModel(value = "productlistparam")
@JsonSerialize(include = JsonSerialize.Inclusion.NON_NULL)
public class ProductListParamextends CommonParam{

@ApiModelProperty(value = " 产品分类ID", required = false )
private Long categoryId;
@ApiModelProperty(value = "产品分类关键字", required = false )
private String keyword;
@ApiModelProperty(value = "产品分类维度", required = false )
private List<String>keys;
@ApiModelProperty(value = "发布时间段", required = false )
private Integer type;

    //get/set.....
}

 

定义好接收参数的实体类,通过@ApiModelProperty注解对每个参数描述,并根据实际参数是否为必填项,最终生成文档。如下图:

技术分享图片

 

 






swagger框架

标签:图片   mes   维度   servlet   log4   conf   res   tab   api   

原文地址:https://www.cnblogs.com/lantu1989/p/9109134.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!