SpringBoot_接口文档_Swagger2

依赖pom.xml

	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
	</dependency>
	<!-- 生成文档 -->
	<dependency>
		<groupId>io.github.swagger2markup</groupId>
		<artifactId>swagger2markup</artifactId>
		<version>1.3.1</version>
	</dependency>

配置文件bootstrap.yml

#-----------swagger2配置---------------
pingruan.base.api-package-scan=com.plxc.service.controller
pingruan.base.api-title=demo
pingruan.base.api-desc=api demo doc

配置源码

    /**
     * swagger2 api配置
     *
     * @author vander
     * @date 2018年11月15日
     */
    @Configuration
    @EnableSwagger2
    @Slf4j
    public class Swagger2Config {
    	
    	@Autowired
    	private BProperties bProperties;
    	
        @Bean
        public Docket createRestApi() {
        	log.info("swagger2 scanning package :"+bProperties.getApiPackageScan());
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage(bProperties.getApiPackageScan()))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title(bProperties.getApiTitle())
                    .description(bProperties.getApiDesc())
                    .version("1.0")
                    .build();
        }
    
    }

@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {

	public static void main(String[] args) {
		SpringApplication.run(SpringbootSwagger2Application.class, args);
	}
}

Swagger2常用注解

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值
 
@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类
 
@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

Swagger2Adoc生成文档

<!-- swagger2-html 需要使用的项目pom文件copy此插件 指令：mvn asciidoctor:process-asciidoc -->
<plugin>
	<groupId>org.asciidoctor</groupId>
	<artifactId>asciidoctor-maven-plugin</artifactId>
	<version>1.5.6</version>
	<configuration>
		<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
		<outputDirectory>src/docs/asciidoc/html</outputDirectory>
		<backend>html</backend>
		<sourceHighlighter>coderay</sourceHighlighter>
		<attributes>
			<toc>left</toc>
		</attributes>
	</configuration>
</plugin>

/**
 * 1、生成swagger静态文件(src/docs/asciidoc/generated/all)
 * 2、copy vander-framework-common的pom.xml中的asciidoctor:process插件
 * 3、mvn asciidoctor:process-asciidoc(src/docs/asciidoc/html)
 * @return
 */
@Bean
public Swagger2Adoc swagger2Adoc() {
	return new Swagger2Adoc(bProperties.getProjectIdPort());//指定项目ip和port，如http://localhost:8083
}


public static class Swagger2Adoc {
	private String rootPath;
	public Swagger2Adoc(String rootPath) {
		this.rootPath = rootPath;
	}
	public void gen() throws MalformedURLException {
		// 输出Ascii格式
		Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC)
				.build();
		Swagger2MarkupConverter.from(new URL(rootPath+"/v2/api-docs")).withConfig(config).build()
				.toFile(Paths.get("src/docs/asciidoc/generated/all"));
	}
}