现在我们的项目中已经有了一个可供外部调用的 REST API 接口, 随着项目的扩展以后会有越来越多的接口, 这个时候就需要同时对外部提供关于接口的详细说明文档, 而 swagger 帮我们使用很少的时间就可以构建出一套接口文档.
首先在 pom.xml 中引用 swagger 所需的依赖.
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <scope>compile</scope>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- </dependency>
然后在代码中开启 swagger
- @Configuration
- @EnableSwagger2
- /** 是否打开 swagger **/
- //@ConditionalOnExpression("'${swagger.enable}' == 'true'") 可以动态控制的开关, 之后再使用
- public class SwaggerConfig {
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2)
- .apiInfo(apiInfo())
- .select()
- .apis(RequestHandlerSelectors.basePackage("com.crossoverjie.netty.action.client.controller"))
- .paths(PathSelectors.any())
- .build();
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- .title("springt boot 从入门到精通 api")
- .description("springt boot 从入门到精通 api")
- .termsOfServiceUrl("https://www.jianshu.com/u/c9deb1bda6ce")
- .contact("https://www.jianshu.com/u/c9deb1bda6ce")
- .version("1.0.0")
- .build();
- }
- }
这一步完成之后, 启动项目, 打开 localhost:8080/swagger-ui.html#/ 就可以看到 swagger 的界面了, 并且我们写好的那个接口也已经躺在那里等我们的调用.
swagger 还有更多的注解帮助我们完善接口文档.
swagger 注解
从源码中可以看到 swagger 提供了这么多注解, 下面我们将常用的几个进行讲解:
- @API
- @API(value = "注解在 controller 类上", description = "注解在 controller 类上")
- @ApiOperation
- @ApiOperation(value = "具体接口描述, 写在 controller 的方法上, notes =" 具体接口描述, 写在 controller 的方法上 ")
- @ApiModelProperty
- @ApiModelProperty(value = "写在接口对应的实体类的属性上", example = "值")
来源: http://www.jianshu.com/p/a3c79088a007