在微服务构建的过程中,你也许发现写的那些restful风格的接口需要编写文档。
文档一般包括要输入哪些参数,哪些参数是必填的,哪些是选填的。还有返回结果的格式以及结果示例。
也许你可以通过在git上写markdown文档来做这些事情。
但每个接口对应的文档地址这些对应关系你又需要关心。
通过swagger,这一切你都不需要做了。
在你编写自己的restful接口的时候,只需要添加一些annotation就可为你自动的生成接口文档。你上面的那些内容都为你自动生成。
甚至连简单的功能测试表单都为你做好了。
总之,你过去需要手来搞的,这里一切为你自动化。
说了这么多,那么怎么使用呢?
目录:
Maven 依赖
@EnableSwagger2 使用
@Api 使用
@ApiOperation && @ApiParam 使用
Docket && ApiInfo 使用
swagger-ui文档首页
swagger页面展示
这里我们以spring boot 为例,
Maven:
首先你需要引入maven依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
@EnableSwagger2
然后springboot上的application类上加上一行注解:
@EnableDiscoveryClient
@SpringBootApplication
@EnableSwagger2 //就是这一行
public class BaseApplication {
然后你就可以在你的rest controller的类上和方法上添加swagger注解来描述你的接口了。
@Api
像下面这样:
@RestController
@Api(tags={"DEMO-SERVICE"})
public class DemoController extends BaseController {
@ApiOperation && @ApiParam
然后就在你的具体的方法上加上:
@ApiOperation(value="计算结果", notes = "根据参数a、b和c计算(a+b)*c的结果")
@RequestMapping(value = "/demo", method = RequestMethod.GET)
public Integer demo(@RequestParam @ApiParam(name="a",value="参数a",required=true)Integer a,
@RequestParam @ApiParam(name="b",value="参数b",required=true)Integer b,
@RequestParam @ApiParam(name="c",value="参数c",required=true) Integer c) {
在Swagger Annotation中:
@API表示一个开放的API,可以通过description简要描述该API的功能。 在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。在
ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。 在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。
ApiParam用于描述该API操作接受的参数类型。
Docket && ApiInfo
你也许发现了,现在给方法写了文档,api的整体说明现在并没有。
你还需要配置api的说明文档。你只需要通过@Bean配置一个ApiInfo就可以了。
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("DEMO-SERVICE")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)//禁用默认的响应
.globalResponseMessage(RequestMethod.POST, //根据自己的需要设计响应
Arrays.asList(new ResponseMessageBuilder()
.code(500)
.message("500 message")
.responseModel(new ModelRef("Error"))
.build(),
new ResponseMessageBuilder()
.code(403)
.message("Forbidden!")
.build()))
.forCodeGeneration(false)
.pathMapping("/")// base,最终调用接口后会和paths拼接在一起
.select() // 选择那些路径和api会生成document
.paths(or(regex("/.*")))//(对指定路径进行监控)过滤的接口
.build()
.apiInfo(apiInfo()); //这里配置apiinfo
}
apiinfo是下面这样:
private ApiInfo apiInfo(){
ApiInfo apiInfo = new ApiInfoBuilder()
.title("Demo-Service服务的RESTful API文档")
.description("该文档使用Swagger2构建,更多详细信息,请访问http://swagger.io")
.license(null)
.licenseUrl(null)
.contact(new Contact("importsource", "", "importsource@gmail.com"))
.version("1.0")
.build();
return apiInfo;
}
swagger-ui页面链接配置
现在基本的文档都写好了。
也许你还在想,我的文档页面是在哪里指定的呢?
很简单,只需要在你的controller中加入下面这样一个方法:
/**
* swagger-ui文档首页
* @return
*/
@ApiIgnore
@RequestMapping("/info")
public ModelAndView swaggerInfo() {
String url="redirect:swagger-ui.html";
return new ModelAndView(url);
}
swagger页面展示
好了,一切都好了。现在我们去swagger的页面看看吧:
你输入参数后,点击try it out按钮,马上就会为你展示出结果以及请求url等等。
没错,一个文档已经为你写好了。而且自带了功能测试界面,让过去你通过浏览器手动输入参数测试的步骤都为你考虑到了。
Swagger可以充当前后端交流的重要桥梁,方便快捷。很实用。
Swagger项目允许你生产,显示和消费你自己的RESTful服务。不需要代理和第三方服务。是一个依赖自由的资源集合,它能通过Swagger API动态的生成漂亮的文档和沙盒,因为Swagger UI没有依赖,你可以把他部署到任何服务器环境或者是你自己的机器。
本文分享自 ImportSource 微信公众号,前往查看
如有侵权,请联系 cloudcommunity@tencent.com 删除。
本文参与 腾讯云自媒体同步曝光计划 ,欢迎热爱写作的你一起参与!