Ape logic, ape logic, ape logic

Swagger is a great help in r&d and can reduce a lot of communication costs on the front and back end. Even at more advanced companies, it can reduce the cost of communicating with testers. So whenever a project adopts the SpringBoot framework, Swagger is almost mandatory.

Unfortunately, Swagger is just a tool. When integrating, you need to modify the POM file to add two JAR packages. There is configuration to be done, and unlucky projects need to modify the contents of WebMvcConfigurer.

In SpringBoot, you can write a starter component for anything that is troublesome. For Swagger’s many reasons, there are many wild starters. Looking at the introduction of the project, strange JAR packages, people who are obsessed with cleanliness always have some unnatural.

Let’s take a look at how Swagger3.0 works in SpringBoot.

Append the starter dependency to POM.xml.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
Copy the code

Access in a browser:

http://localhost:8080/swagger-ui/
Copy the code

You have documentation (yes, not swagger-ui.html). Finished? Finished. It’s that simple. Some say you need to join on the main class@EnableOpenApiNotes, but you don’t need them.

What has changed?

Swagger3 configuration in SpringBoot is not a bit simpler. More importantly, a package name like IO. Springfox looks so lofty that it can’t help but create a sense of trust.

Swagger does the following in 3.0:

  • Removed verbose POM dependencies, includingspringfox-swagger2
  • kill@EnableSwagger2Annotation, zero configuration
  • A lot of dependencies are removed, like Guava, which is fresher

In fact, everything is done in the AutoConfig file, just like any other starter. From the source, we see that swagger and UI components are enabled by default.

Springfox. Documentation. Enabled configuration, can be a key to turn it off. Springfox. Documentation. Swagger – UI. Enabled parameters, can control the display of the UI.

From Swagger’s dependency, we see an interesting concept: openAPI. There’s a Specification for this thing. Documentation, it turns out, is a pain point on the Internet, not just in old-fashioned project companies.

https://swagger.io/specification/
Copy the code

The article is so long that we’ll call Specification the document O_O of the document.

About the certification

Of course, there are changes. If your project uses a permission control component like Spring Security, don’t forget to whitelist it. Something like this.

String[] SWAGGER_WHITELIST = {
        "/swagger-ui.html"."/swagger-ui/*"."/swagger-resources/**"."/v2/api-docs"."/v3/api-docs"."/webjars/**"
};
httpSecurity.cors()
        .antMatchers(SWAGGER_WHITELIST).permitAll()
Copy the code

Back swagger address, you access V2 also into, access v3 also into. Anyway, I import YAPI, RAP2 API management platform, it will work.

Integration is easier, but ApiOperation annotations are as ugly as ever.

Sometimes, when we use authentication like JWT, we need to construct a token in the Header at request time.

Swagger goes two ways.

First, through the global Auth authentication configuration.

As shown in the picture above, click the Auth button in the upper right corner to pop up the dialog box.

At this point, you’ll need a SwaggerConfig file. Here is the complete code.

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi(a) {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .build()
                .securitySchemes(security());
    }
private List<SecurityScheme> security(a) {
        ApiKey apiKey = new ApiKey("Authorization"."Authorization"."header");
        return Collections.singletonList(apiKey);
    }
    private ApiInfo apiInfo(a) {
        return new ApiInfoBuilder()
                .title("mbye api")
                .description("nothing here")
                .version("1.0") .build(); }}Copy the code

The other option is to manually enter a token each time a request is made. Similar to the following:

The configuration is as follows:

private List<RequestParameter> globalRequestParameters(a) {
    RequestParameterBuilder parameterBuilder = new RequestParameterBuilder()
            .in(ParameterType.HEADER)
            .name("Authorization")
            .required(false)
            .query(param -> param.model(model -> model.scalarModel(ScalarType.STRING)));
    return Collections.singletonList(parameterBuilder.build());
}
Copy the code

Use the following code to use it.

.globalRequestParameters(globalRequestParameters());
Copy the code

End

All in all, the overall feeling is very good. Maybe it is my illusion, I feel the page is also a lot smoother. But because the new version is still relatively new, there are many small bugs. For example, the Auth page succeeds, but there is no value in the curl request parameter.

But despite the flaws, Swagger3 is worth a try. What’s more, it costs almost nothing to change.

​