Swagger2在SpringBoot中的集成指南

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<!-- swagger -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.7.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.7.0</version>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

package com.wuwenze.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @author wuwenze
 * @date 2019/1/28
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.wuwenze.api"))
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("某电商平台在线API文档")
        .description("这是详细描述详细描述详细描述详细描述详细描述详细描述")
        .contact(new Contact("吴汶泽", "https://wuwenze.com",
            "wenzewoo@gmail.com"))
        .version("1.0")
        .build();
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

package com.wuwenze.api;

import cn.hutool.core.util.RandomUtil;
import com.wuwenze.entity.Token;
import com.wuwenze.support.mvc.entity.ResultBody;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author wuwenze
 * @date 2019/1/28
 */
@RestController
@RequestMapping("/UserApi")
@Api(value = "UserApi", description = "用户相关接口")
public class UserApi {

  @ApiOperation(value = "用户登陆", notes = "登陆成功后返回Token")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "username", value = "用户名", required = true, paramType = "query", dataType = "String"),
      @ApiImplicitParam(name = "password", value = "密码", required = true, paramType = "query", dataType = "String")
  })
  @RequestMapping(value = "/login", method = RequestMethod.POST)
  ResultBody<Token> login(String username, String password) {
    return ResultBody.ok(
        Token.builder().token(RandomUtil.simpleUUID()).build()
    );
  }
}

1
2
3

<!--国际化操作：选择中文版 -->
<script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
<script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>