swagger 介绍及两种使用方法

一：swagger是什么？

方法一：使用第三方依赖（最简单的方法）

1、在pom.xml文件中添加第三方swagger依赖（）

 
   
   
     com.spring4all 
    
   
     swagger-spring-boot-starter 
    
   
     1.7.0.RELEASE 
    
   

方法二：使用官方依赖

1、在pom.xml文件中添加swagger相关依赖

 
   
   
     io.springfox 
    
   
     springfox-swagger2 
    
   
     2.7.0 
    
   
   
   
     io.springfox 
    
   
     springfox-swagger-ui 
    
   
     2.7.0 
    
   

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

2、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

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 Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台 APIs") .description("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台") .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin") .contact("程序猿") .version("1.0") .build(); } } 

三、具体使用

1、在API上做一些声明

//本controller的功能描述 @Api(value = "pet", description = "the pet API") public interface PetApi { //option的value的内容是这个method的描述，notes是详细描述，response是最终返回的json model。其他可以忽略 @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = { @Authorization(value = "petstore_auth", scopes = { @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"), @AuthorizationScope(scope = "read:pets", description = "read your pets") }) }, tags={ "pet", }) //这里是显示你可能返回的http状态，以及原因。比如404 not found, 303 see other @ApiResponses(value = { @ApiResponse(code = 405, message = "Invalid input", response = Void.class) }) @RequestMapping(value = "/pet", produces = { "application/xml", "application/json" }, consumes = { "application/json", "application/xml" }, method = RequestMethod.POST) ResponseEntity 
  
    addPet( //这里是针对每个参数的描述 @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body); 
  

2、设定访问API doc的路由

在配置文件中，application.yml中声明：

springfox.documentation.swagger.v2.path: /api-docs 

这个path就是json的访问request mapping.可以自定义，防止与自身代码冲突。

API doc的显示路由是：http://localhost:8080/swagger-ui.html

如果项目是一个webservice，通常设定home / 指向这里：

@Controller
public class HomeController {

    @RequestMapping(value = "/swagger")
    public String index() {
        System.out.println("swagger-ui.html");
        return "redirect:swagger-ui.html";
    }
}

四：swagger的常用API

1、api标记

2、ApiOperation标记

ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：

@ApiOperation( value = "Find purchase order by ID", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order, tags = {"Pet Store"}) 

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-V8AEIZ2l-24)(http://ozpb6wow8.bkt.clouddn.com/22.png)]

3、ApiParam标记

ApiParam请求属性,使用方式：

public ResponseEntity 
  
    createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user) 
  

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-5veQGqo7-25)(http://ozpb6wow8.bkt.clouddn.com/3.png)]

4、ApiResponse

5、ApiResponses

6、ResponseHeader