Spring Boot入门样例-220-swagger2自动生成接口文档

Spring Boot入门样例-220-swagger2自动生成接口文档

开发文档从函数上直接生成，避免文档维护不一致。本demo演示如何使用swagger2自动生成接口文档。

前言

本Spring Boot入门样例准备工作参考：

• Spring Boot入门样例-001-Java和Maven安装配置
• Spring Boot入门样例-003-idea 安装配置和插件
• Spring Boot入门样例-005-如何运行

pox.xml

必要的依赖如下，具体参见该项目的pox.xml

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

配置文件

resources/application.yml配置内容

# Swagger界面内容配置
swagger:
  title: Bootan API接口文档
  description: Bootan Api Documentation
  version: 1.0.0
  termsOfServiceUrl: https://github.com/funsonli/spring-boot-demo
  contact:
    name: Funsonli
    url: https://github.com/funsonli/spring-boot-demo
    email: funsonli@163.com

代码解析

Swagger2Config.java 如下

@Slf4j
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.title}")
    private String title;

    @Value("${swagger.description}")
    private String description;

    @Value("${swagger.version}")
    private String version;

    @Value("${swagger.termsOfServiceUrl}")
    private String termsOfServiceUrl;

    @Value("${swagger.contact.name}")
    private String name;

    @Value("${swagger.contact.url}")
    private String url;

    @Value("${swagger.contact.email}")
    private String email;

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("Authorization", "access-token", "header"));
        return apiKeys;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    @Bean
    public Docket createRestApi() {

        log.info("加载Swagger2");

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(name, url, email))
                .version(version)
                .build();
    }
}

StudentController.java 如下 @ApiOperation中写接口功能

@Slf4j
@RestController
@RequestMapping("/student")
@Api("学生管理")
public class StudentController {

    @ApiOperation("学生列表")
    @GetMapping({"", "/", "index"})
    public String index() {
        return "index";
    }

    @ApiOperation(value = "查看学生", notes = "单个学生详情")
    @GetMapping("/view/{id}")
    public String view(@PathVariable String id) {
        return "view " + id;
    }

}

1. index方法先判断是否登录，否则跳转login
2. get的login方法显示resources/templates/site/login.html文件，该文件会引入resources/templates/common/head.html，以及使用resources/static中的css和图片文件
3. 登录后显示resources/templates/site/index.html中内容

运行

点击运行

浏览器访问 http://localhost:8080/swagger-ui.html

参考

• Spring Boot入门样例源代码地址 https://github.com/funsonli/spring-boot-demo
• Bootan源代码地址 https://github.com/funsonli/bootan
• https://github.com/xiaoymin/Swagger-Bootstrap-UI

附

如果您喜欢本Spring Boot入门样例和样例代码，请点赞Star