03- Swagger2构建Restful文档

1.在pom.xml中添加添加Swagger2依赖

<!--swagger2 依赖开始-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>
<!--swagger2 依赖结束-->

2.在服务启动类的同级创建Swagger2配置类SwaggerConfig

package com.study.model;

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 {
    @Bean
    public Docket createRestApi() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("使用Swagger2构建RESTful APIs")
                .description("客户端与服务端接口文档")
                .termsOfServiceUrl("http://localost:8080")
                .contact("test swagger")
                .version("1.0.0")
                .build();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.study.model"))
                .paths(PathSelectors.any())
                .build();
    }
}
注意：  上面的包名是对应工程的包  我的包是这样的

上述代码中，通过@Configuration注解，让Spring来加载该类配置，通过@EnableSwagger2注解来启用Swagger2。

再通过createRestApi函数创建Docket的Bean之后，apiInfo是用来创建接口文档的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

3.给对应API接口创建描述信息

package com.study.model.controler;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping(value="/user")
public class UserController {
    @ApiOperation(value="获取用户信息", notes="欢迎用户")
    @RequestMapping(method = RequestMethod.GET)
    public String user(){
        return "hello world!";
    }
    @ApiOperation(value="获取用户信息", notes="根据{username}获取对应用户信息")
    @RequestMapping(value="/get/{username}",method = RequestMethod.GET)
    public String get(@PathVariable("username") String username){
        return "welcome," + username;
    }
    @ApiOperation(value="登录", notes="根据URL中的username、pwd进行用户登录验证")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", required = true,paramType = "query", dataType = "string"),
            @ApiImplicitParam(name = "pwd", value = "密码", required = true,paramType = "query", dataType = "string")
    })
    @RequestMapping(value="/login",method = RequestMethod.GET)
    public String login(@RequestParam String username, @RequestParam String pwd){
        return "user:" + username + ",password:" + pwd;
    }
}

4.运行后，访问 http://localhost:8080/swagger-ui.html 就能看到之前所展示的RESTFUI API的页面

03- Swagger2构建Restful文档

猜你喜欢