swagger2 快速上手 quick-start

如何使用swagger？

1.在pom.xml中引入相关依赖

 io.springfox
 springfox-swagger2
 2.7.0


 io.springfox
 springfox-swagger-ui
 2.7.0

2.在config/swagger包中建立SwaggerConfig类（此工程的总体概述）

package com.bocom.smp.config.swagger;
​
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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
@EnableSwagger2
public class SwaggerConfig {
 /**
 * 初始化创建Swagger Api
 */
 @Bean
 public Docket createRestApi() {
 return new Docket(DocumentationType.SWAGGER_2)
 // 详细信息定制
 .apiInfo(apiInfo())
 .select()
 // 指定当前包路径
 .apis(RequestHandlerSelectors.basePackage("com.bocom.smp.controller"))
 // 扫描所有 .apis(RequestHandlerSelectors.any())
 .paths(PathSelectors.any())
 .build();
 }
 /**
 * 添加摘要信息
 */
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
 // 标题
 .title("")
 // 描述
 .description("register-server主要用于普通服务的增删改查等")
 // 文档版本
 .version("1.0.0")
 .license("Apache License Version 2.0")
 .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
 .build();
 }
}

3.在config包下的WebMvcConfig类中加入如下内容（swaggerUI映射）

import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
​
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
 registry.addResourceHandler("swagger-ui.html")
 .addResourceLocations("classpath:/META-INF/resources/");
 registry.addResourceHandler("/webjars/**")
 .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

4.这里给出一个使用swagger注解的示例controller

这个示例中使用了lombok，非必选。请自行引入依赖。

package com.bocom.smp.controller;
​
import io.swagger.annotations.*;
import lombok.Data;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
​
@RestController
@RequestMapping("/swagger")
@Api(description = "SwaggerTest接口")
public class SwaggerTestController {
​
 @GetMapping("/v1/get/{id}")
 @ApiOperation("GET接口")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
 })
 public String get(@PathVariable String id) {
 return "hello swagger2 "+id;
 }
  
 @PostMapping("/v1/post/map")
 @ApiOperation("POST接口")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "map", value = "MAP参数", required = true, dataType = "Map")
 })
 public String postMap(@RequestBody Map map) {
 return "hello:  "+map;
 }
  
 @PostMapping("/v1/post/list")
 @ApiOperation("POST接口")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "list", value = "list参数", required = true, dataType = "List")
 })
 public String postList(@RequestBody List list) {
 return "hello:  "+list;
 }
  
 @PutMapping("/v1/object")
 @ApiOperation("PUT接口")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "foo", value = "用户ID", required = true, dataType = "Foo")
 })
 public String object(@RequestBody Foo foo) {
 return foo.toString();
 }
  
  
 @DeleteMapping("/v1/delete/{id}")
 @ApiOperation("DELETE接口")
 @ApiImplicitParams({
 @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
 })
 public String delete(@PathVariable String id) {
 return "\t"+id;
 } 
}
// 实体类同样可以使用注解
@Data
@ApiModel(description = "foo实体类")
class Foo{
 @ApiModelProperty(value = "姓名")
 private String name;
 @ApiModelProperty(value = "年龄")
 private String age;
}
​

5.工程启动后，通过访问http://IP:PORT/APP_NAME/swagger-ui.html来查看接口情况