吴汶泽

纸上得来终觉浅,绝知此事要躬行。

  1. 引入依赖Swagger2及Swagger2 UI
  2. 构建配置文件(基于JavaConfig)
  3. 定义需要发布文档接口
  • 国际化实现
  • 引入依赖Swagger2及Swagger2 UI

    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>

    构建配置文件(基于JavaConfig)

    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()
    );
    }
    }

    国际化实现

    • 国际化文件位于springfox-swagger-ui-2.7.0.jar/META-INF/resources/webjars/springfox-swagger-ui/lang目录中
    • 实现国际化(用自己的swagger-ui.html 代替原生swagger-ui.html)
      • 新建 src/main/resources/META-INF/resources/swagger-ui.html 文件
      • 把swaager-ui jar包中 /META-INF/resources/swagger-ui.html的内容复制进去
      • 在新建的swagger-ui.html补充插入以下js:
    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>

    本文最后更新于 天前,文中所描述的信息可能已发生改变