springboot + swagger接入指南

springboot + swagger接入指南

在做网关的时候,需要提供大量的Restful接口,而且接口时常会有调整,所以在此接入swagger根据controller动态生成文档.

github地址:withing

jar包引入:

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.8.0version>
dependency>

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.8.0version>
dependency>

springboot引入在这不作说明.

提供config类:

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()//build模式,返回一个建造者
                .apis(RequestHandlerSelectors.any())//api的配置路径
                .paths(PathSelectors.any())//扫描路径选择
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("title") //文档标题
                .description(appDescription)//接口概述
                .version("1.0") //版本号
                .termsOfServiceUrl(String.format("url"))//服务的域名
                .license("LICENSE")//证书
                .licenseUrl("http://www.123.com")//证书的url
                .build();
    }

编写controller和domain类:

UserController

@Api(value = "/api", description = "swagger示例接口", tags = "example")
@RestController
@RequestMapping(value = "/api", produces = {"application/json"})
public class UserController {

    @ApiOperation("通过userId搜索User")
    @GetMapping("/query/{userId}")
    public User query(@PathVariable Long userId) {
        User user = new User();
        user.setUserId(userId);
        user.setName(RandomStringUtils.random(5, true, false));
        return user;
    }

}

User

public class User {

    private Long userId;

    private String name;
    /**
    * 省略getter,setter方法
    */
 }

swagger文档展示

在浏览器中输入 localhost:8080/swagger-ui.html

localhost:8080按自己的域名和端口自行变化

swagger展示图片

若需要生成静态文档请看withing