Springboot Swagger 在线接口文档

1、Swagger配置

（1）引入依赖

<swagger.version>2.7.0</swagger.version>

</properties>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>${swagger.version}</version>

</dependency>

<groupId>com.drore.cloud</groupId>

<artifactId>swagger-bootstrap-ui</artifactId>

</dependency>

（2）Swagger配置类

package com.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.annotations.ApiOperation;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class Swagger2 {
         @Bean
         public Docket createRestApi() {
                   return new Docket(DocumentationType.SWAGGER_2)
                                     .apiInfo(apiInfo())
                                     .select()

//                                  .apis(RequestHandlerSelectors.basePackage("com.demo.controller")) //把controller包下的所有方法都转为restful api
                           .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //只把有@ApiOperation注解的方法转为restful api
                                     .paths(PathSelectors.any())
                                     .build();
         }
         private ApiInfo apiInfo() {
                   return new ApiInfoBuilder()
                                     .title("Spring Boot中使用Swagger2构建RESTful APIs")
                                     .description("更多Swagger2说明 https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel")
                                     .termsOfServiceUrl("http://localhost:8080/")
                                     .contact(new Contact("wzf", "https://swagger.io/", "[email protected]"))
                                     .version("1.0")
                                     .build();
         }

}

（3）swagger的其他使用方式

参考：https://github.com/SpringForAll/spring-boot-starter-swagger

下载github上面的源码，放到自己工程下面，之后就可以在配置文件里面配置，省去上面的代码配置

swagger:
  title: RESTful APIs
  description: API接口文档
  version: 1.0
  globalOperationParameters[0]:
    name: access_token
    description: token
    parameterType: query
    modelRef: string
    required: true
  docket:
    env:
      base-package: com.demo.web.environment.controller
    system:
      base-package: com.demo.web.system.controller

2、访问与调试

http://localhost:8080/doc.html

调试：

3、参考

Swagger-Bootstrap-UI是Swagger的前端UI实现,采用jQuery+bootstrap实现,目的是替换Swagger默认的UI实现Swagger-UI,使文档更友好一点：

https://git.oschina.net/xiaoym/swagger-bootstrap-ui

https://oss.sonatype.org/#nexus-search;quick~swagger-bootstrap-ui

4、Api接口添加全局参数

private List<Parameter> parameters (){
    ParameterBuilder aParameterBuilder = new ParameterBuilder();
    aParameterBuilder
            //参数类型支持header, cookie, body, query etc
            .parameterType("query")
            //参数名
            .name("access_token")
            .description("token")
            //指定参数值的类型
            .modelRef(new ModelRef("string"))
            //非必需false，这里是全局配置，然而在登陆的时候是不用验证的
            .required(true).build();
    List<Parameter> aParameters = new ArrayList<Parameter>();
    aParameters.add(aParameterBuilder.build());
    return aParameters;
}



@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .groupName("base")
            .globalOperationParameters(parameters())
            .select()
            //只把有@ApiOperation注解的方法转为restful api
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build();
}

5、问题记录

1在通过swagger2在线测试接口时候，如果url中有{id}，需要添加paramType=”path”，否则无法从路径中获得id值
@ApiImplicitParams({
@ApiImplicitParam(name =” id”, value = ”用户ID”, required = true, paramType =”path”, dataType =” Long”),
@ApiImplicitParam(name = ”user”, value = ”用户详细实体user”, required = true, paramType =” body”, dataType = ”User”)
})
要定义paramType， paramType 有五个可选值： path, query, body, header, form

6、生成离线文档

（1）创建文件夹

asciidoctor

asciidoctor有maven插件，可以自动把acsiidoc文件转成html和pdf，能自动生成目录，非常方便

先在工程下创建docs/asclidoc这个文件：

文件内容是：

include::{generated}/overview.adoc[]

include::{generated}/definitions.adoc[]

include::{generated}/paths.adoc[]

意思就是引入三个文件

（2）Maven配置

<build>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-maven-plugin</artifactId>

</plugin>

<groupId>org.asciidoctor</groupId>

<artifactId>asciidoctor-maven-plugin</artifactId>

<sourceDirectory>${project.basedir}/docs/asciidoc</sourceDirectory>

<sourceDocumentName>index.adoc</sourceDocumentName>

<generated>${project.build.directory}/asciidoc</generated>

</attributes>

</configuration>

<!-- Since each execution can only handle one backend, run separate executions

for each desired output type -->

<id>output-html</id>

<goals>

<goal>process-asciidoc</goal>

</goals>

</configuration>

</execution>

</executions>

</plugin>

</plugins>

</build>

（2）运行maven build

运行成功后，在E:\Workspaces\Comba-Api\target\generated-docs文件夹下会生成

Springboot Swagger 在线接口文档

猜你喜欢